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CAPITULO 1: 
Introduction 


There are several MVC frameworks for developing WEB 
applications, and perhaps you may be asking yourself why should 
you learn a new one. The main motivation is to try to use a tool that 
will make you worry with nothing more than your business rules. 


“Play” already comes with many infrastructure decisions taken on by 
you. For example: 


A server that will be used to publish the application 
Framework for object-relational mapping 

Native support for setting up environments, such as test, 
homolog, and production 

Utility classes for making integration and acceptance tests 
easier to be written 

Compiled views 

Tasks ready to package and distribute the application 

Plugin to monitor the database evolution and keep track of the 
creation of your charts 

Highly performatic and scalable because of its asynchronous 
nature. 


Note that all of this infrastructure alone is useless; the project 
development team spends several hours assembling such 
infrastructure project after project. With this part entirely ready, the 
developers may be mostly concerned with just writing business rules 
related to the application, which will probably be much more 
profitable for the company. 


1.1 Following or not the specification 


In order to provide much more than competitors, Play had to make a 
bold architectural decision. The specifications governing the 


development of Java web applications were not designed to provide 
the features offered by the framework. In order to avoid 
workarounds, Play decided not to follow the specifications of 
JavaEE. At first it may seem that you lose much, as it is now strongly 
coupled to it, but stop and think for a second. How often do you keep 
switching the implementation? How many times has a project in 
which you were participating had to change the JPA implementation? 
Or implementation of the JAX-WS specification? The one that 
handles the creation and use of Web services. 


Based on that, the Play team decided not to give much importance 
to the specification. Going the other way, they managed to create a 
framework that offers you several technologies for the different 
layers of your application and with everything already integrated. 
These types of frameworks are known in the market as Full Stack 
and have been proving to be more productive than those of 
competitors. Examples already well-established are Rails, written in 
Ruby, and Django, written in Phyton. 


1.2 No pause for class reloading 


Another bad characteristic of web application development in Java is 
the famous mandatory reload that the application has to suffer when 
a Class is changed. Think about how many times you have been 
waiting for Tomcat’s hot deploy after any change. And think about 
when you were with a logged-in user and the same was lost after the 
change. This is a recurring problem that makes developers lose 
precious minutes to inactivity. Therefore, many developers develop 
in debug mode all the time to try to minimize this waiting time. 
However, what about when a configuration file is changed, for 
example, some .properties or the persistence.xml of your 
application using JPA? There is no way for these examples; you 
have to wait for the redeploy until changes are shown. 


As everything in Play is integrated, this problem has also been 
solved. Any file that you change in your application is automatically 
reloaded by Play, much like what happens during development using 
scripting languages like Ruby and Php. Programmers coming from 
.NET platform are also used to it due to the high level of integration 
between the platform frameworks and the IDE for development. 


1.3 Designed to be scalable 


One last point | want to discuss in order to convince you to devour 
this book as if your project depended on it is the power of scalability 
of Play. Even today, the most common solution to scale an 
application is to add more servers and then balance the load 
between them. This is a solution that will eventually have to be 
taken, but what you mostly want is to delay an increase in design 
complexity due to this decision. If your application is installed on 
several different servers, how will it handle data of the session user? 
This is just one example of added complexity. 


Seeking to improve this aspect, Play uses a server called Netty, 
which was built already prepared for dealing with requests 
completely asynchronously. And it goes further, since it is of no use 
for your server to have this support if its APIs do not have the same 
principle. The core of Play is based on the Scala language, which 
runs over the JVM and has a strong concern with concurrence and 
parallelism. Moreover, the Akka project was implemented, which is 
the main project of the Java world nowadays when speaking about 
these characteristics. Therefore, everything within the framework 
happens in a non-blocking way, which greatly increases the 
scalability of just one instance of your application. 


And if you still need to scale the application horizontally, including 
more servers, Play turns this into a trivial task. It was designed not to 
maintain any state, being stateless. Without a state, there is no 


reason to worry about in which server the request will fall. Your load 
balancing will be used at full capacity. 


1.4 The adventure begins 


If the above arguments have sharpened your curiosity, start reading 
the book now! In the next chapter you will already have a "Hello 
World" built in a matter of minutes. And enjoy,! If you realize you 
already have all of this, just go back to LeanPub and ask for a 
refund; you have a time period of up to 45 days for doing so. 


CAPITULO 2: 
First Application 


To begin, let's create our first application with Play! Stay tuned, 
because in a moment you are going to have a Hello World to show 
your colleagues. The first thing we need to do, as with any 
framework, is to download Play by accessing the project website, 
download link. The download of Play, as well as Java JDK, go far 
beyond the classes that will help us in writing the project. A set of 
tools will be downloaded that will help us create the project, start and 
stop the server, package the project, and utilize other features. 


2.1 Creating the first project 


After the download, choose the most suitable location for extracting 
the zip file. In order to facilitate our communication, from now on the 
chosen path for the extraction will be called $pathToPlay. Now let's 
create our first application; in a typical way, we can call it 
helloworld. Simply open a terminal, go to your project folder, and 
type the following: 


1 sh **SpathToPlay**/activator new helloworld 


Don’t forget to replace the $pathToPlay by your installation directory. 
When the line above is run, a Play message will be displayed to you 
with some options to be used as a template for your project, 
something like that: 


Fetching the latest list of templates... 


Browse the list of templates: http://typesafe.com/activator/templates 
Choose from these featured templates or enter a template name: 


-$ a 
(hit tab to see a list of all templates) 
> 


Fig. 2.1 


Choose the option number 3. This template will make activator to 
create a project with the minimum necessary. 


Just choose option 2, and a folder with the project name will be 
created. In a simple and practical way, we have created a new 
project. Inside the project folder, you can see that Play has created a 
specific structure for us. Try holding your curiosity; | know it is 
difficult, but it is not interesting to go on dissecting folders without 
having a real need. The important thing now is to mount the server 
and see our first application running. 


2.2 Running for the first time 


Again, we need to access the installation path of Play. By the way, 
typing this path all the time tends to get really annoying; therefore, let 
“s add it to the path of our system to make it simpler. On Unix 
systems, this process is as simple as running the following 
command: 


Version 2.3 forward, everything that is needed to run your project, is 
in the the folder created by Activator. Now, in order to access the 
console, from the folder of the project, just type this command: 


./activator 


If you are doing this for the first time, you will need to wait. All 
dependencies should be downloaded before you can start the 
project. Remember, wait for whole process until the end. After this 
phase, the Play's console will be opened in your terminal. 


The Play console will be opened on the terminal, similar to the 
following: 





‘alberto luizsouza@Alberto-Luiz-Souzas-MacBook-Pro-3 helloworld $ ~/ambiente/plays/play-2.2.2/play 
[info] Loading project definition from /Users/albertoluizsouza/ambiente/desenvolvimento/scala/helloworld/project 
[info] Set current project to helloworld (in build file:/Users/albertoluizsouza/ambiente/desenvolvimento/scala/helloworld/) 


eh E ee 
rou Vo id 
| JILIN 7 


| = 
play 2.2.2 built with Scala 2.10.3 (running Java 1.7.0_05), http://www. playframework. com 


> Type "help play" or "license" for more information. 
> Type "exit" or use Ctrl+D to leave this console. 


[helloworld] $ E 


Fig. 2.2 


Now let’s enter the run command and the Play server will start. 
Notice that the server runs, by default, in the 9000 port. Access the 
URL http://localhost:9000 and that’s it! Our first application is already 
working. Part of the page that will be displayed is like the one below: 


Your new application is ready. Browse APIs 





Play framework 2.3.0 is out! Check it out here. 


Welcome to Play Browse 


Congratulations, you've just created a new Play application. This page will help you with the next few Local documentation 


steps. Browse the Java API 


You're using Play 2.2.2 Start here 


Using the Play console 


Why do you see this page? Sonu ei vente od OF 
Your first application 

The conf/routes file defines a route that tells Play to invoke the Application. index action 

whenever a browser requests the / URI using the GET method: 


# Home page 
GET / controllers .Application.index() 


Play has invoked the controllers.Application.index method: 


Fig. 2.3 


Press Ctrl+D and then enter to stop the server and, to leave the 
console, type exit. 


Exporting the sdk path 


Every time we need to create a new project, we have to type the 
path to the activator download folder, $pathToPlay/activator. To 
avoid that, we can export this to path of your system. In Unix 
systems this process is as simple as execute the command bellow: 


export PATH=S PATH:$ caminhosdkplay 
We can't forget to let the file $pathToPlay/activator executable: 
chmod a+x Scaminhosdkplay/activator 


In the earlier versions, this same executable used to be called play 
instead of activator. 


2.3 Conclusion 


In this chapter we built our first application draft, hopefully without 
many difficulties. In the next chapters we will start building a real 
application, and—really, don’t go to sleep yet—there are many 
emotions coming in the next scenes! 


CAPITULO 3: 
Setting up the application 


Now that we tried a first example and are more familiar with the flow 
of project creation, let us begin to build the application we are going 
to use during the book. Our project will be based on Agendatech, an 
application written using the Rails framework, which attempts to map 
events that are to take place in Brazil. The interesting thing about 
being based on Agendatech is that we already have a known domain 
where you can see all the potential that Play has to offer. 


To give you a taste, we bring you the features that we plan to 
implement as you read the book. Remember, for every problem that 
comes, we will use a Play facility to help us solve it. Below is the list: 


Registration of events that are to occur 

Registration of events categories 

Events listing 

Upload of the event logo in different formats 

Event approval 

Email of approval 

Improved performance and scalability of the application 
Events compatible with an external application, i.e., a mobile 
Login through Facebook and Twitter 


The index page of our project may be similar to this: 





Eventos Entrevistas Cursos Admin de banners Admin de posts Admin de entrevistas 


InfiNet Wireless remodela roadshow e promove encor Divulgue 
1 3 encomenda’ 
Rio Grande do Sul RubyConf Q2 
Fevereiro oy LOCAWEB Ser eee ae 


Destaque 


== Capacitação em Análise de Pontos de Função: Medigg Sobre a RubyConf 2013 eS 
1 5 =~" de Software em São Paulo = 

a lo 
Fevereiro 


São Paul 





Capacitação em Análise de Pontos de Função: Mediçt 
1 7 de Software em Belo Horizonte 
Minas Gerais 
Março 





Fig. 3.3 


3.1 Creating the project and importing it to 
eclipse 


The first step is to create a project, and for this we will use the sdk 
we downloaded. As we already moved the sdk to the path of our 
operating system, just choose the folder you like and run the 
following command line on the _terminal_: 


| play new agendatech 


Now we have the project structure created. A detail that has not 
been discussed so far is the /DE we are going to use for the 
development. For ease, we will choose Eclipse. This step may 
sometimes hinder our flow. Who never spent a lot of time trying to fix 
the classpath, or who never got hung up because one of the IDE 
setup files did not come together with the project? To help on this 
part, Play brings with it a task for importing the project to Eclipse. 
The first step is to access the folder where the project has been 
created. Now, at the command line, run the following instruction: 


l play 


This is going to open the command console of Play. If you want to 
take a look at everything that is available, just enter the following: 


L help play 


A list of the available commands will be presented. Below is an 
example: 


[agendatech-en] $ help play 
Welcome to Play 2.2.2! 


These commands are available: 


classpath Display the project classpath. 

clean Clean all generated files. 

compile Compile the current application. 

console Launch the interactive Scala console (use :quit to exit). 
dependencies Display the dependencies summary. 

dist Construct standalone application package. 

exit Exit the console. 

h2-browser Launch the H2 Web browser. 

license Display licensing informations. 

package Package your application as a JAR. 

play-version Display the Play version. 

publish Publish your application in a remote repository. 
publish-local Publish your application in the local repository. 
reload Reload the current application build file. 

run <port> Run the current application in DEV mode. 

test Run Junit tests and/or Specs from the command line 
eclipse generate eclipse project file 

idea generate Intellij IDEA project file 

sh <command to run> execute a shell command 

start <port> Start the current application in another JVM in PROD mode. 
update Update application dependencies. 


Fig. 3.1 


Eclipse is precisely one of the commands which allow us to create 
the entire structure needed to import the project to Eclipse. Without 
wasting much time, go on and import the application. Just enter the 
command in the console, as shown below: 


1 eclipse 


Now just import the project into your Eclipse. After importing it, the 
structure of your project should be like this one, as follows: 





Ae agendatech-en 
b app 
> |B test 
P = Referenced Libraries 
> =} JRE System Library [Java SE 8 [1.8.0_20]] 
P E conf 
P (= project 
» (= public 
P (= target 
=| build.sbt 


[=h 


=) README 





Fig. 3.2 


To check if everything is right, enter the command run in the terminal 
to launch the application. If everything is OK, the standard Play 
welcome screen should be displayed. Let's now stop the server, and 
for that just press ctri+ d_. 


3.2 A bit about folder structure 


The more curious reader should have noticed that inside the project 
and target folders are files in Scalalanguage. Do not worry; the Play2 
core is written in Scala, but we will be dealing only with Java in 
almost every development. 


Another interesting point is the package structure that Play has 
generated for us. As previously discussed, instead of spending time 


on how to separate this kind of thing, the framework has already 
generated a source folder, called app, with the following packages: 


e controllers 
e views 


Do not be concerned with them right now. In the next chapter, we will 
begin to develop the first application functionalities, and of course, 
they will be around! 


3.3 Conclusion 


In this chapter, the idea of the project that we are going to develop 
throughout the book has been presented. We will use Agendatech 
because it has several features that are common in different 
projects. And that's what we should worry about, business rules! The 
framework will be in charge of the infrastructure details. 


CAPITULO 4: 
Beginning the conference registration 


Now that the Project has been created, it is time to begin the 
implementation of the functionalities. The first thing to be done is the 
registration screen for new events, so we begin to use the structure 
provided by Play. The screen is very simple, just an HTML. 


1 <html> 

2 <body> 

3 <form action="/conferences" method=" POST"> 

4 <input type="text" id="name" name="nome" 
value="" > 

5 <input type="text" id="contactEmail" 

6 name="contactEmail"value=""> 

7 <textarea id="description" 
name="description" > 

8 </textarea> 

9 <input type="text" id="site" name="site" 
value="" > 

0 <input type="submit" value="New 


onference"> 
11 </form> 
2 </body> 
3 </html> 





For the moment, our view is no big deal, just a simple HTML. A file 
called new_conference.scala.html will be created and placed in the 
app/views/conferences package. And now we can learn about 
some details of Play. The first one is the scala word in the file name. 
Play uses this language to enable the writing of dynamic pages. 
Think of it as another view technology that you have studied. Let's 
just remember some: 


e JSP. Widely used in conjunction with Java frameworks in the 
market. 


e Velocity. Once it was a powerful alternative to JSPs. 

e Freemarker. Also widely used due to its template mechanisms. 

e ERB. Used in the Ruby world, especially with the Rails 
framework. 


The use of the Scala language is for the view of Play just like the 

_Expression Language_ is for JSPs. It has some very interesting 
points, which will be discovered as long as its functionalities are 
developed. Another point to notice is that the page should be created 
inside the views/conferences package. The views package is what 
Play uses as a Standard to store pages. All pages created in it geta 
special treatment of the framework. One that is going to be used is 
the fact that the page is transformed into a class that can be 
accessed from everywhere. Inside the views, you are free to create 
the structure you want. Throughout this book, the Play standards will 
be respected, and the reason is that we do not want to waste time on 
infrastructure! 


The highlight of having a view that is compiled is that it is not 
necessary to wait for the page to run to discover an error. If you want 
to check if everything that is being developed is being compiled, 
access the terminal in your computer, go to your project’s folder, and 
enter the command play. 


After the Play console has opened, enter ~run. The run command, 
as already seen, starts the server, and the ~ before it is for Play to 
keep recompiling any alterations and to keep applying them to the 
project. This way, any possible error is promptly shown at the 

terminal. In Play, everything is compiled, not just the Java classes. 


4.1 Understanding a little more about Controllers 


The first thought might be that to access this page you should write 
the name of the file in the browser, and that’s it. Remember, your 
page may contain logics such as: 


* conference listing * messages of success and error presented * 
values recovered to be displayed in the form fields 


If the access were direct, all this logic would probably be placed into 
the view, which would result in serious maintenance problems. We 
would be mixing many responsibilities and writing Java code in an 
inappropriate place. Because of that, Play prohibits direct access to 
any view. The idea is that you always go through a class that can 
retrieve some objects that are necessary for the page, and this class 
takes the decision on which view will be called. These classes are 
called Controllers. Note that the name itself indicates that it controls 
the flow of execution of your web application. The controllers created 
in the application, following the standards, will be placed in the 
controllers package. As the views package, we will keep on the 
standards so as not to waste time configuring unnecessary details. 


1 import play.mvc.*; 
2 public class ConferencesController extends 
Controller { 


public static Result form() { 
return null; 


} 


YO OP W 


iy 


There is an interesting detail in relation to the imports that will be 
used throughout the book. As Play supports the development in 
Scala or Java, they had to make a division in imports. Be aware that 
any import with the api package is from the Scala world. The use of 
Scala classes in its Java code should always be done with much 
analysis. The package used for the Java world is play.mvc. 


Just inherit from Controller and your class will have earned several 
methods ready to handle the web requests. We have taken the 
opportunity to add a method whose purpose is to direct the user to 
the new events page. 


The return of the new method is an object type _Result_. This is the 
class that represents its Response on a project using Play. Through 
it, we can return a different status and the type of content that will be 
returned to the user in our application. If we wanted to return only 
200, indicating that all worked out, we would have the following 
code: 


1 import play.mvc.*; 
2 public class ConferencesController extends 
Controller { 


public static Result form() { 
return ok(); 


} 


~I O OB W 


} 


The _ok()_ method is provided by the super class _Controller_. The 
detail is that we do not want to return only this status; it is necessary 
to return the page that appears in the browser. For doing so, the ok 
method has a variation that receives an object type _Content_. 
There are various implementations for the Content interface, and the 
one we will use represents an HTML return, the HTML class. 


At this moment, Play greatly facilitates our work. As stated earlier, 
every written view is automatically compiled into a scala class. We 
can access it to invoke the render method and obtain an object type 
_HtmL. 


1 import play.mvc.*; 

2 public class ConferencesController extends 
Controller { 

3 

4 public static Result form() { 

5 Html view = 

views.html.eventos.new conference.render (); 
6 return ok (view); 

7 } 

8 } 





You must be wondering where this class came from, with such a 
name, new_conference. To satisfy your curiosity, take a look at the 
source folder called classes_managed, which was generated by 
Play at the time of the project creation. 


Y (’classes_managed - {Users falbertoluizsouva/z 
H £4 (default package) 
H £6 controllers 





= Wiews.htmil.conferences 


b a new_conference.class 
Fig. 4.1 


This class has a static method called render that returns the Html 
object with the content of our page. This is one of the great ideas of 
Play; compiling the page makes silly errors, like using the wrong 
variable or even syntax error name, to be found without having to 
access the page. When our page gets a little more dynamic, we will 
be able to see even more benefits that this feature brings to us. 


4.2 Accessing the page 


Now the controller method that leads to the page already exists, but 
the most important thing is still missing: access to the screen. For 
example, we want the user to enter the address 
http://localhost:9000/conferences/new, so it should be able to 
access our screen. Let's see what happens if we do this now: 


Action not found 





ay GET /assets/$file<.+> controllers.Assets.at(path:String = "/public", file:String) 


Fig. 4.2 


Play displayed a very friendly error page to the developer, advising 
that the URL typed has not yet been configured. What is missing is 
to associate the address requested with the method of a controller, 
also called Action by Play. This setting is performed on the routes 
file, which is in the conf folder of the project. This folder, as the 
name implies, contains all the necessary configuration files for our 
application. 


The routes file is a simple text file in which we map the relations 
between the system URLs and the actions that address them. 


1 + Routes 

2 +f This file defines all 

3 # application routes (Higher priority routes 
first) 

4 

5 GET /conferences/new 
controllers.ConferencesController.form() 

6 

i # Map static resources from 

8 tithe /public folder to the /assets URL path 
9 GET /assets/*file 
controllers.Assets.at(path="/public", file) 


Note that it has a specific format. The first part indicates the verb that 
should be used to access the action. The most common options are 
POST and GET, but any other that is supported can be specified. 


Then, the next part indicates the URL that is being set up. We will 
discuss more about this URL later because additional settings can 
be made. Finally, we'll indicate what action will address the request 
to this URL. Now that everything is set up, just access the URL and 
the page is displayed normally. 


Note that everything has been done without stopping the server. At 
the beginning we entered ~ run, and Play took care of updating 
everything for us. 


Now let's conduct an experiment. It is not unusual to write the wrong 
class name or the wrong method name. If it happens, another user- 
friendly error screen appears. 





Compilation error 


object ConferencesControlle is not a member of package controllers 


In /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/conf/routes at line 5. 


# This file defines all application routes (Higher priority routes first) 





t—~—~~ 
[5] GET /conferences/new controllers .ConferencesControl1le.form() 


# Map static resources from the /public folder to the /assets URL path 

















GET /assets/*file controllers.Assets.at(path="/public”, file) 


Fig. 4.3 


The routes file is also compiled! As already said, almost everything 
in Play is compiled. The same error could have already been caught 
by the console itself. For every change we make, Play compiles and 
updates it with the application still running. 











[info] Compiling 3 Scala sources and 2 Java sources to /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/target/scala-2.10 
/classes... 

[error] /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/conf/routes:5: object ConferencesControlle is not a member of pa 
ckage controllers 

[error] GET /conferences/new controllers.ConferencesControlle. form() 

[error] /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/conf/routes:5: object ConferencesControlle is not a member of pa 
ckage controllers 

[error] GET /conferences/new controllers.ConferencesControlle. form() 

[error] two errors found 

[error] (compile:compile) Compilation failed 


Fig. 4.4 





The compilation error was just a detail that helped us. We will still 
need to use the generated class to refer the URLs. Do not bother 
stopping for lunch; now jump into the next chapter to continue with 
the event registration. A situation you may have found strange is that 
the Event class was not yet created. No worries. As we do not need 
it now, it was left for a later time. 


4.3 Conclusion 


In this chapter, we studied a little of Play’s general structure. A view 
and a controller were built, and we bound the URL with the controller 
through the routes file. We noticed how Play is also heavily based on 
standards. Everything already has its definite place; therefore, the 
framework could help us a lot by maintaining the focus on the 
business rules and not on the infrastructure. Moreover, the fact that 
almost everything is compiled became a differential because errors 
are found earlier and with messages far friendlier than the ones 
contained in StackTraces_, generated by runtime errors. All of this 
will be further studied according to the needs of Agendatech. 


CAPITULO 5: 
Dealing with requests 


Now that we have the registration form and the users can now 
browse it, the system must be able to save a new conference. First, 
it is worth remembering the view of the form. 


1 <html> 

2 <body> 

3 <form action="/conferences" method=" POST"> 

4 <input type="text" id="name" name="nome" 
value=""> 

5 <input type="text" id="contactEmail" 

6 name="contactEmail"value=""> 

7 <textarea id="description" 
name="description" > 

8 </textarea> 

9 <input type="text" id="site" name="site" 
value=""> 

10 <input type="submit" value="New 


conference"> 
11 </form> 
12 </body> 
13 </html> 





Note that the action of the form points to the address conferences. 
Curiousity probably appeared again , and you may have already 
clicked on the registration button. Let's just remember what happens. 


Action not found 





1 GET /conferences/new controllers.ConferencesController.form() 


2 GET /assets/$file<.+> controllers.Assets.at(path:String = "/public", file:String) 


Fig. 5.1 


We had already gone through this problem when the user tried to 
access the view of the registration. It is necessary to make the URL 
binding with the action responsible for handling the request. Let's 
use the routes file again. 


1 #old routes here 
2 POST /conferences 
controllers.ConferencesController.create () 


If you follow this step, you realize that the Play console accused a 
compilation error because the create action has not yet been created 
in the ConferencesController controller. 


1 import play.mvc.*; 
2 public class ConferencesController extends 
Controller { 





3 
4 public static Result form() { 
5 Html view = views.html.conferences. 
6 new conference.render (); 
7 return ok(view); 
8 } 
9 
10 public static Result create() { 
11 //what are we gonna do here? 
12 } 





As we have not yet evolved to implement the code of the new action, 
we can use a special *Result* of Play indicating that the code 
implementation is missing. 


1 public static Result create () { 
2 return TODO 
3} 


The constant TODO contains an object type result that generates a 
response with the 501 status, indicating that the URL has not yet had 
its logic implemented. Along with the status, an error page also 
returns, following the Play standard layout to signal problems in the 
application. 


€ Œ | D localhost:9000/conferences Ly & = 


TODO 





Action not implemented yet. 





Fig. 5.2 


Another point that can still be improved before implementation of the 
registration is the way in which the view form refers to the URL of the 
action responsible for the functionality. Notice that, in the action 
form’s attribute, the URL is placed in a _hard coded_ way. 


1 <form action="/conferences" method="POST"> 


If we change this URL in the routes file, the error will only be found 
when someone tries to register an event. Not that that's a very 
serious problem, as this would have probably been tested before, 
but remember: the more errors that are caught at the compilation 
time, the faster we can evolve with the application. In order to help 
the programmer in this task, Play provides an object with methods to 
access all the routes statically defined. 


1 <form 
action="@routes.ConferencesController.create()" 
2 method="POST"> 


For running dynamic code in the views of Play, it is necessary to use 
@ in front of the variable. If you try to draw a parallel, the reader may 
recall the <? used in PHP or the ${} used in the JSPs. Note that a 
variable called routes is available. 


This object is what Play calls Reverse Router. We can use it in all 
views so that you can access any routes defined by the application. 
It’s not magic; just check the code generated in the 
classes_managed source folder. 


Y (2 classes_managed - /Users/albertoluizsouza/z 
P £6 (default package) 
Y 4 controllers 
b H javascript 
>» £4 ref 
+ ReverseAssets.class 
ih ReverseConferencesController.class 
¥ iat routes.class 
> & javascript 
> G ref 
W Assets 
W ConferencesController 
a <clinit>Q : void 
€ routes{} 
b £6 views.html.conferences 
Fig. 5.3 . 


If there is a typing error, the Play console acknowledges a 
compilation error, and the error may be quickly corrected. The same 
will happen if the user tries to access the application because he 
forgot to look at the console. 


Compilation error 


value creat is not a member of controllers.ReverseConferencesController 





In /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/app/views/conferences/new_conference.scala.html at line 3. 





2 <body> 
E <form action="@routes .ConferencesController.freat()" method="POST "> 
<input type="text" id="name" name="nome" value="" > 
<input type="text" id="contactEmail" name="contactEmail"value=""> 
<textarea id="description" name="description” ></textarea> 
<input type="text" id="site” name="site"” value="" > 


<input type="submit" value="New conference"> 


Fig. 5.4 


5.1 Receiving the form parameters 


We must begin by implementing the logic of the registration of a 
conference. The first thing to do is to get the parameters sent 
through the form. For this, an object is provided that contains all the 
information of the request. 


1 public static Result create() throws IOException 
{ 

2 Request request = request(); 

3 return TODO; 

4 } 


The request method was inherited from the class _Controller_. It 
has several methods for interacting with the current request of the 
application. Now we need to get the parameters that were sent on 
the request. For instance, let’s get the name of the event. 


public static Result create() throws IOException 


Request request = request (); 

3 System.out.println(request.body(). 

4 asFormUrlEncoded().get ("name") [0]); 
5 return TODO; 


Notice how extended the code is. It’s very distant from the simplicity 
of getting a parameter when using the API of the Java Servlets. 


1 request.getParameter ("nome") 


The motivation for this complexity is that Play has been designed 
since the beginning to be a framework that can be used for a 
standard web application, which will really get values from a form, as 
well as for an application that runs as a service. The object type 
request already has methods to retrieve values in JSON and XML, 
for example. 


request .body().asFormUrlEncoded () ; 
2 request.body().asJson(); 
3 request.body().asxXml(); 


NO FR 


The three methods that have been shown above are responsible for 
dealing with different data formats. One is still missing, the method 
we are going to use when the files are sent by the form. The first one 
is the most common of all, it handles the format sent by the forms we 
write on the pages. Note that the client can choose between all these 
formats when sending information to the server. This is called 
Content-Type and is specified by the header Accept at the HTTP 
request. 


However, getting one parameter at a time is very laborious. In fact, if 
it were required to treat each separately, we would probably not use 
this framework. To facilitate this work, Play offers an object whose 
class is called Form, which is able to receive parameters and return 
us an object that makes more sense to our application. Under the 


hood, it uses a project from the Spring framework, called spring 
databinder. 


1 public class ConferencesController extends 


Controller { 
p 


a 


3 private static Form<Conference> 
conferenceForm = 

4 Form. form(Conference.class); 

5 

6 public static Result create() throws 
IOException { 

y Form<Conference> formFromRequest = 
conferenceForm. 

8 bindFromRequest () ; 

9 Conference conference = 
formFromRequest.get(); 

10 return TODO; 

11 } 

12 } 





Notice that, after acquiring the Form object, just invoke the method 
bindFromRequest and it returns a new Form with the request values 
associated with our object. Then, just use the get method to retrieve 
the object. The form also contains other methods, for example one to 
verify validation errors. We will handle them later on. 


An interesting detail is that ultimately we need the class Conference. 
It doesn’t have much at all; for now it is a simple class with private 
attributes and methods of access. A classic Java Bean. 


public class Conference { 


private Integer id; 

private String contactEmail; 
private ConferenceState state; 
private String description; 
private String site; 


NYO OP WNE 


private String twitter; 
private String name; 


public void setName(String name) { 
this.name = name; 


} 


public void setDescription (String 
scription) { 
this.description = description; 


PRPOOrRPPRPRPE HE 
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} 





LO œœ 


//others setter e getters 





Note that the names of the form fields are equal to the names we 
give to our setters. This is how the binding is done at Play. The Form 
object can still be smarter. It manages to make the binding between 
a Map by simulating the parameters and also its object. Therefore, if 
the input data is not by a form but by a text file that should be 
processed, we take each line of the file, generate a map, and then 
generate our objects with ease. 


public static Result create() throws IOException 


Map<String, String> parameters = 


i 

{ 

2 //cead the file 

3 

4 //ouild a hashmap based on each line 


5 Conference conference = conferenceForm. 
6 bind (parameters).get(); 

7 return TODO; 

8 } 


The more careful reader might be wondering why the methods of 
controllers, i.e., the actions, are static. Most frameworks in the 
market handle controllers like normal classes, which can have a 
lifecycle, instance variables, etc. On the other hand, Play has 
another approach: the controller is nothing more than a transformer 


of the values coming from the HTTP request for objects that make 
sense to the application domain. Based on this premise, they believe 
that the controller should not save the state of anything; because of 
that, it utilizes the static approach. 


This was also the reason we declared the attribute conferenceForm 
as static. Another question that may come to mind is: If the attribute 
is static, how can Play differentiate the requests coming from diverse 
clients? The answer is that it uses a very common class in Java 
projects that need to bind objects associated with a Thread (the 
client). This class is the _ThreadLocal_! 


5.2 Conclusion 


In this chapter, we saw how to take advantage of the compilation of 
our routes file to refer the URLs in the views of our application. In 
addition, we took an important step because we are now able to 
handle values of any form and transform them into objects of our 
domain. To sum up, we learned how to let our action keep answering 
a Status that indicates that such a feature has not yet been 
implemented with the use of the constant TODO. 


CAPITULO 6: 
Saving and listing the conferences 


Now that the object of type Conference is already built based on 
information sent by the form, it's time to save it in the database. And 
here we are going for the direct use of a persistence framework. The 
default option in the market is Hibernate. However, we will adhere to 
the option suggested by Play, and which better supported by it, 
which is the use of the Ebean framework. The idea is basically the 
same as Hibernate, and Ebean also supports the JPA annotations to 
perform the Object Relational mapping. The biggest difference is 
focused on the API ease of use. Hibernate typical problems—like 
Lazy Load, weak support to paging, constructions of partial queries, 
and those when we just want to bring part of the information of the 
object—were resolved by Ebean. 


6.1 Saving with Ebean 


Our objective is to save the conference in the database. Therefore, 
to quench the curiosity, let’s begin by presenting the necessary code 
for such a task. 


1 1 aoa static Result create() { 

2 Form<Conference> formFromRequest = 

3 conferenceForm.bindFromRequest () ; 

4 Conference conference = formFromRequest.get(); 
Ebean.save (conference); 

6 return TODO; 


The Ebean class is the entry point of the framework. It is similar to 
the EntityManager of JPA, or the Session in case the reader uses 
Hibernate directly. The biggest difference is that it does not keep any 
information about the object sent; that’s why the methods are static. 


6.2 Setting up Ebean 


The next step is to set up the database access information. In our 
case, we are going to use MySQL just because it is well known and 
easy to install. The first step is to add the necessary annotations in 
the class Conference. 


YO OP WN FE 


Hi eC ee ee a a l 
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@Entity 
public class Conference { 


} 


@Id 

@GeneratedValue 

private Integer id; 

private String contactEmail; 
@Enumerated (EnumType.STRING) 
private ConferenceState state; 
@Column (columnDefinition = "text") 
private String description; 
private String site; 

private String twitter; 
private String name; 





//getter e setters 


No big deal. If you already know these annotations, you can skip to 
the next paragraph. Below is a list of the meanings of the 
annotations used. 


e @Entity. Your class will represent a table in the database. 

e @ld. The annotated attribute is the primary key of the table. 

e @GeneratedValue. The key generation will be done 
incrementally to be decided by Ebean. In the case of MySQL, 
auto-increment will be used. 


e @Enumerated. The generated column will be of the type, and 
the stored values will have the same names of the Enum 
constants. 

e @Colum. Additional information for generating the table. In the 
case of the description, it is informed that the column must be 
text type. 


Setting up database access 


Now that the class is properly annotated, we need to add the 
information of the database access. Everything should be in the file 
application.conf that is located in the conf folder, which is already 
known due to the use of the file routes. Remember, your settings will 
be in this folder. 


1 application.secret="..." 
2 # The application languages 


4 application.langs="en" 


# Database configuration 
8 # You can declare as many datasources as you 
want. 

# By convention, the default datasource is 

named S%default%% 
10 # 
11 db.default.driver=org.h2.Driver 
12 db.default.url="jdbc:h2:mem:play" 
13 do.default.user=sa 
14 db.default.password="" 


Note that the language settings, cookie token for generating cookies 
(we discuss later), and configuration database, among others, are all 
in this file. We will learn more things over the course of the book. 
The important part for us now is the details of database access. It is 
necessary to configure the driver, URL, username, and password. 


db.default.driver=com.mysgql.jdbc.Driver 


db.default.url="jdbc:mysql://localhost/agendatech _ 
play" 

3 db.default.user=root 

4 db.default.password="" 


Setting up the scan of Ebean 


Another necessary step is to indicate the packages that Ebean 
should look for in annotated classes. That way, it will be able to load 
them and identify some setup problem, such as an annotation used 
in the wrong way. All of this still in the application.conf. 


1 # Ebean configuration 


# You can declare as many Ebean servers as you 
want. 
4 # By convention, the default server is named 
6sdefault%% 
5 # 


6 ebean.default="models.*" 


An interesting detail, but not very common in today's applications, is 
that the Ebean permits you to configure a variety of its managers for 
different databases. For example, in the above configuration 
“ebean.default’ was used, which is Ebean’s default configuration. 
We could have created another entry, for example 
“ebean.legacyDatabase’, pointing to another package if there was a 
need to use two databases in the same application. The application 
would look like this: 


1 EbeanServer server = 
Fboean.getServer ("legacyDatabase") ; 
2 server.save (obj); 





For anyone who knows JPA, it is similar to Persistence Unit. 


Setting up the driver and a bit of SBT 


Almost everything is already set up; there is just one last detail, 
which is to add the MySQL driver in our application. Ebean already 
comes with the jar of HSQLDB, which is a database widely used for 
application tests but never in production ones. In order to add the jar, 
it is necessary to work with the SBT file, the building tool most used 
in the Scala world. The objective is the same of Maven, Ant, Gradle, 
and others. The reader does not need not worry; we will just work on 
a little basics of SBT. 


At the root of the project, there is a file called build.sbt. Let's take an 
initial look. 


1 name := "agendatech" 


3 version += "1, 0-SNAPSHOT" 





5 libraryDependencies ++= Seq( 
javaJddbc, 
jJavaEbean, 
cache 


11 play.Project.playJavaSettings 


There are already some settings, as the project name and some 
standard libraries in Play project. Furthermore, there is an additional 
setting indicating that the Java development version was chosen. 
Basically, some Scala code is written in this file. Let's change the list 
of dependencies, adding MySQL. 


name := "agendatech" 


version := "1.0-SNAPSHOT" 





5 libraryDependencies ++= Seg ( 


javaJddbc, 

jJavaEbean, 

cache, 

"mysql" % "mysql-connector-java" % "5.1.20" 


) 
Ll2 play.Project.playJavaSettings 


It is important that the spaces between the lines are preserved. It is a 
requirement of the SBT. Now that we added this information, open 
the Play console in your project. If the console is already open, with 
the server running, press CTRL+D and then Enter to stop it. With 
the server stopped, type reload to reload the information of the file. 


Okay, now just type update for Play to download the new 
dependency. After the upgrade, type eclipse for your project to be 
updated. 


6.3 Creating the tables with the Evolutions 


The classes are already mapped, so the database configuration is 
ready. Finally we can save the data of the conferences. The last 
missing details are to create the database itself and the tables. 


To create the database, access the terminal on your computer, and 
open the mysql. If you are using Mac or Linux, the command would 
be ‘mysql -u root’. Remember that if you have specified a password, 
it will be requested now. It is also good to change the 
application.conf providing the password. To create a new database, 
type ‘create database agendatech_play;. 


It is now necessary to create the tables. To do this, we just make an 
experiment. First we start the server, “~run’. After that, we will 
access any URL of our application. For example, we could access 


http://localhost:9000, the app entry. When we make this attempt, a 
screen like the following will be displayed. 


Database 'default' needs evolution! 





An SQL script will be run on your database - 
This SQL script must be run: 
1 





# --- Rev:1,Ups - 7c2b28f 


2 create table conference ( 

3 id integer auto_increment not null, 

4 contact_email varchar(255), 

5 state varchar(16), 

6 description text, 

site varchar(255), 

8 twitter varchar(255), 

J) name varchar(255), 
1® constraint ck_conference_state check (state in ('ACRE', ‘ALAGOAS', ‘AMAZONAS', 'BAHIA', ‘CEARA', ‘DISTRITO_FEDERAL" , 'ESPIRITO_SANTO' , ‘GOIAS' , ‘MINAS_GERAIS' , 'MATO_GROSSO' , ‘MATO_GROSS( 
11 constraint pk_conference primary key Cid)) 


Fig. 6.1 


It is an error screen saying that we need to apply an evolution in the 
database. The idea is that Play generates updating scripts of the 
tables based on the mappings of their classes. To prove this theory, 
let’s take a look at the folder conf/evolutions/default it contains the 
script that was generated based on the annotations taken in the 
Evento class. 


1 # --- Created by Ebean DDL 
2 # To stop Ebean DDL generation, remove this 
comment and 


3 # start using Evolutions 

4 

5 # --- !Ups 

6 

7 create table conference ( 

8 id integer 
auto increment not null, 

9 contact email varchar (255), 
10 state varchar (16), 





11 description text, 





site varchar (255), 
twitter varchar (255), 
name varchar (255), 
constraint ck conference state check 
(state in ('ACRE', 'ALAGOAS', 'AMAZONAS', 
"BAHTA', 'CEARA', ‘DISTRITO FEDERAL', 
"ESPIRITO SANTO', 'GOITAS', 'MINAS GERAIS', 
'MATO GROSSO', 'MATO GROSSO SUL','PARA', 
"PARAIBA', 

'PERNAMBUCO', 'PIAUI', 'PARANA', 


"RIO DE JANEIRO’, 'RONDONIA', 'RIO GRANDE SUL' 


23 
24 
25 


(id) ) 


26 
Al 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 


. 
7 


,'RORAIMA', 'SANTA CATARINA', 
"SERGIPE’, "SRO PAULO’ ,’TOCANTING*)), 
constraint pk conference primary key 


# --- !Downs 
SET FOREIGN KEY CHECKS=0; 
drop table conference; 


SET FOREIGN KEY CHECKS=1; 


Also, the constraint of our Enum that represents the states is 
respected. Moreover, it has a special kind of comment interpreted by 
Play, indicating which part of the script is responsible for creating 
and which one is responsible for destroying things in the database. 
Another important detail is that we can create our evolutions 
regardless of our classes. 


Here, we just mixed business with pleasure. We will devote a 
chapter solely to dealing with the Evolutions and the possibilities 
being offered. 


To apply the evolution, just click on the button "Apply this script now". 
Another interesting point is that, to deal with the order of evolutions, 
Play creates a table in the system containing the date of application 
of the evolution, the script used, and everything else. The table 
name is play_evolutions. 


Okay, after that we can now register how many events we want. 


6.4 Listing the conferences and the Redirect 


Now that the registration for the event is already being done, we 
need to list it. Here, the process is already known. Let’s keep the 
Play console running to monitor any problems that may arise, and 
we will start the implementation. Let's begin with View. This is a 
screen with a very simple listing. We will pay attention to the layout 
at the end of the book. 


<html> 
<body> 
<ul> 
Qfor (conference <- conferences) | k 
conference details here 


pi> 


8 </body> 
9 </html> 


W N He 
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Note that | have taken the liberty of adding a dynamic code in our 
view. We will need the list of conferences so it will be possible to 
display their information. By the way, the console of Play is 


complaining that this view does not compile, which makes sense 
since there is not yet a variable conferences_. 


The first detail to note is that to run any dynamic code in the view, it 
is necessary to use @ in front of it. It is similar to PHP’s <% %> or 
JSP’s ${} in the traditional Java world. We now need to figure out 
how to access the variable conferences. Let's just stop and think a 
bit about it. It has been argued that the view of Play is compiled and 
turns into a class. This class has a static method called *render*. 
Just as a reminder, it has already been used. 


1 public static Result form() { 


2 return 
ok(views.html.conferences.new conference. render () ) 








CO ve 


} 


Now, if the method needs information from outside to run, the most 
natural is that arguments are passed to it. It is exactly in this way that 
Play works; when a view needs objects from the controller, they are 
passed via parameter. 


| 


le] (conferences: List [Conference] ) 


2 <html> 

3 <body> 

4 <ul> 

5 Qfor (conference <- conferences) { 
6 <li> 

- 





@conference.getName() - 
@conference.getSite () 





8 </li> 
9 } 
LO </ul> 
11 </body> 
12 </html> 


If the parameters are required, they should be the first thing to be 
declared in the view in the same way as how packages should be 


the first thing declared in Java classes. And as we have seen, if the 
View has no parameter, just do nothing. As we are using the Java 
version of Play, the package java.util is already imported in view so 
that we make use of the classes. 


Now that the page has been built, it is necessary to create the action 
that provides access to it. There is nothing brand new here; let's just 
use what we have studied. 


1 public static Result list(){ 

2 List<Conference> conferences = Ebean. 
3 find(Conference.class).findList(); 
4 return ok(views.html.conferences.list. 
5 render (conferences) ); 


The interesting part is the passing of parameters to the render 
method of the class generated from View. In the most common 
technologies, the attentive reader will remember that this parameter 
passing is done by binding a string with an object. For example: 
‘request.setAttribute("Cconferences",conferences) leads to typing 
errors in the view or the controller itself, which are only discovered 
when already being executed or even running in production. This is 
another point in which the compilation helps us a lot. 


To conclude, it is necessary to register the route in the routesfile. 


1 #other routes 
2 GET /conferences 
controllers.ConferencesController.list() 


Performing redirect 


To conclude our initial flow of registration and listing, we need that, 
after the registration of a new conference, the user goes to the page 
of the listing. A first approach could be the following: 


public static Result create() { 
Form<Conference> formFromRequest = 


NO fF 


conferenceForm. 
3 bindFromRequest () ; 
4 Conference conference = 


formFromRequest.get (); 
Ebean.save (conference); 
return list(); 


IO VU 


} 


As we already have the listing method, which returns a Result to us, 
we can reuse it and send the user to the listing screen. The problem 
with this approach is that, for the browser, the last request was a 
post to localhost:9000/conferences. If our user presses F5 to reload 
the page, the browser will try to make a second post with the latest 
data sent, which would result in a double register. 


Here it is necessary to tell the browser that we want to make a new 
request to the address from the list of events, called client redirect. 
This way, if the user presses F5, he will actually load the list again. 
This is a very common pattern in the web called Always redirect 
after Post. Let's see how our code would be: 


1 public static Result create() { 
2 Form<Conference> formFromRequest = 


conferenceForm. 
3 bindFromRequest () ; 
4 Conference conference = 


formFromRequest.get(); 

5 Ebean.save (conference); 

6 return 

redirect (routes.ConferencesController.list()); 


7 
/ 
$ } 


The redirect method, also inherited from the Controller class, creates 
a result with status 303, which means See other, and it passes to 
the browser the next URL to be browsed. If you install _Chrome 
tools _ or Firebug, it can be easily checked. 


6.5 Conclusion 


This chapter has studied the initial part of integrating the persistence 
framework, passing through the use of Ebean, up to the 
configuration of the database access required to make connections. 
In addition to that, we saw some of the evolutions of Play, which will 
still be used much more in the book. Finally, we arrived in the list 
view, where we saw that the pages can take parameters as well as 
methods that are commonly written. Also, we performed a redirect 
after registration of the new conference since we did not want 
anyone pressing F5 and doubling these entries. 


Do not stop reading. The next chapter will address data validation, 
as well as converting types of values that are not supported by 
default in Play. 


CAPITULO 7: 
Converting and Validating Data 


The registration is already perfectly functional. The problem now is 
that it is necessary to store the conference time period, since 
Agendatech intends to show the conferences that are yet to happen 
and not what has already happened. To do this, we are going to add 
two more attributes in the class Conference. 


1 @Entity 

2 public class Conference { 

3 

@Id 

@GeneratedValue 

private Integer id; 

private String contactEmail; 
@Enumerated (EnumType.STRING) 
private ConferenceState state; 
@Column(columnDefinition = "text") 
private String description; 
private String site; 

private String twitter; 
private String name; 

private Calendar startDate; 
private Calendar endDate; 
//getter e setters 
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It is now necessary to add these two fields in the registration form. 
Let’s not waste time with stylized calendars and so on; the input of 
the type date of HTML5 will be used. 


1 <html> 
2 <body> 
3 <form 


action="@routes.ConferencesController.create()" 
4 method="POST"> 


value="" 
19 





<input type="text" id="name" name="nome" 
> 
<input type="text" id="contactEmail" 
name="contactEmail"value=""> 
<textarea id="description" 
name="description"> 
</textarea> 
<select name="state"> 
@for(state <- ConferenceState|.\values))| 


Kloption value="@state.name"> 
@state.name 
</option> 
} 

</select> 
<input type="text" id="site" name="site" 
> 
<input type="text" id="twitter" 


name="twitter" 


20 
21 


value=""_> 
<input type="date" id="startDate" 


name="startDate" 


22 
23 


value=""> 
<input type="date" id="endDate" 


name="endDate" 


24 
25 


value=""> 
<input type="submit" value="New 


conference"> 
26 </form> 
27 </body> 
28 </html> 


7.1 A little problem with the Evolution of Ebean 


Now, with the changes made, we can try to access our application 
again. When the application is accessed, the Play error page is 


displayed asking to apply the evolution generated because of our 
change. 


Database ‘default" needs evolution! 





An SQL script will be run on your database - 


1 # !!! WARNING! This script contains DOWNS evolutions that are likely destructives 


# --- Rev:1,Downs - 7c2b28f 
SET FOREIGN_KEY_CHECKS=0; 


6 drop table conference 
SET FOREIGN_KEY_CHECKS=1; 


10 # --- Rev:1,Ups - 3b410e2 
1 create table conference ( 
12 id integer auto_increment not null, 
13 contact_email varchar(255), 
14 state varchar(16), 
description text, 
16 site varchar(255), 
17 twitter varchar(255), 
name varchar(255), 
19 start_date datetime, 


2 end date datetime 


Fig. 7.1 





However, that is not quite what we want. We do not want to drop the 
table that already exists in order to add new fields. The intention is to 
add new columns in the existing table. At this moment, the evolution 
of the table is being controlled by Ebean, which is integrated into 
Play. To get around with this, it is necessary to delete the first 
comments of the evolution. 


1 # --- Created by Ebean DDL 
2 # To stop Ebean DDL generation, remove this 
comment and start 


3 # using Evolutions 


There is an obscure detail here. Reading the comments, it seems 
that only the second line should be removed, but in fact, we will 
remove the 2 lines. 


A comment that actually executes code is weird; you cannot deny. 
Perhaps the best solution Play could have used was a mechanism- 
style Rails migration. We could have classes that execute the 
evolutions with defined methods of ups and downs. 


Now that Ebean stopped generating the evolutions for us, we should 
create the same manually. Therefore, we create the file 2.sql. 


lL ge Ups 


> alter table conference add start date date; 
4 alter table conference add end date date; 


9 # --- !Downs 


ll alter table conference drop column start date; 
12 alter table conference drop column end date; 


As a reminder, we will have a chapter just related to evolutions. For 
example, what if another developer, on another machine, also 
creates an evolution named 2.sql? What should be done? How 
should we apply the downs? These questions are separated into 
another chapter so we don't lose focus on the application now. 


7.2 Problem in converting 


With the new added columns and Conference class changed, we 
can now try to register a new conference with the time period! The 
problem is that when we try to make the registration, we receive an 
exception of the type //legalStateException. 


Execution exception 


(11legalStateException: No value] 


In /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/app/controllers/ConferencesController.java at line 24. 





public static Result create() { 
Form<Conference> formFromRequest = conferenceForm.bindFromRequest(); 
| 24] Conference conference = formFromRequest.get(); 
5 Ebean.saveCconference); 


return redirect(routes.ConferencesController.list()); 


public static Result listQ){ 


Fig. 7.2 


It does not tell us much. We can also look a bit on the Play console, 
but the stack displayed does not provide much information about this 
error. To try to know a little more, we can deepen the level of the 
Play log. Remember, the right interpretation of errors makes a 
significant difference in productivity. To change the properties of the 
Play log, we have to change the application.conf file. 


# Root logger: 
logger. root=ERROR 


N FR 


# Logger used by the framework: 
logger.play=INFO 
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# Logger provided to your application: 
logger.application=DEBUG 
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To increase the level of information about problems arising from the 
core framework, let’s change the entry logger.play to DEBUG or 
TRACE. Even so, the log still does not tell us clearly what is 
happening. 


Well, the problem that is happening is that Play, unfortunately, does 
not know how to convert the value sent by our date fields into a 
Calendar. It can only work with the java.util.Date type, which is 
already outdated. We need to configure the framework to get the 


String sent by the form and turn it into the type we need. It is in this 
scenario that the Formatters of Play arrive. 


7.3 Building your formatter 


First of all, it is necessary to create a class that inherits from 
SimpleFormatter. 


public class Html5CalendarFormatter 
extends SimpleFormatter<Calendar> { 


} 


WN FF 


Notice that Generics is used for the signatures of the methods that 
should be implemented in order to become more intuitive. The 
abstract methods defined by this class are: 


* Calendar parse(String value, Locale locale). In order to get a string 
and convert. * String print(Calendar value, Locale locale). In order to 
get value and show as string. 


The implementation should be as follows: 


1 package converters; 
2 


3 public class Html5CalendarFormatter 
4 extends SimpleFormatter<Calendar> { 
5 
6 private SimpleDateFormat formatter = 
7 new SimpleDateFormat ("yyyy-MM-dd") ; 
8 
9 @Override 
10 public Calendar parse(String value, Locale 
locale) 
11 throws ParseException { 
12 if (!value.trim().isEmpty()) { 





13 Date date = formatter.parse(value); 
14 Calendar calendar = 
Calendar.getInstance(); 

15 calendar.setTime (date); 

16 return calendar; 

17 } 


return null; 
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21 @Override 
22 public String print (Calendar value, Locale 
locale) { 
23 if (value != null) { 

return formatter.format (value.getTime()) ; 
} 


return ""; 
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Note that we used an uncommon format for Brazilians when parsing 
the date. This is because the input of the type date of HTML5 always 
sends the date in this format. Based on the language of the browser, 
the correct mask is displayed to the user. However, the parameters 
are always sent in the "yyyy-MM-dd" format. Therefore, the work is 
facilitated for the server, not depending on Locale to know the 
correct format. Although we have the implementation of the print 
method, the same is not important at this time. Do not think too much 
about it; let’s continue our journey. 


With Formatter implemented, it is necessary to register it in Play so 
it can be used for the conversions. This registration needs to be 
done only once. The framework already provides a class that has 
listeners that run at specific events of our application, for example 
when it is started. This class is GlobalSettings. 


The work is just to create a class that inherits from GlobalSettings. 


import java.util.Calendar; 

import converters.Html5CalendarFormatter; 
import play.Application; 

import play.GlobalSettings; 

import play.data.format.Formatters; 


> 
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public class Global extends GlobalSettings { 
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@Override 

10 public void onStart (Application app) { 

Formatters.register(Calendar.class, 
new Html5SCalendarFormatter()); 


JRO 





I 
> O MN EF 
= 


12 4 


Note that we did not specify any package, because it should be in 
the default package of your application. There are also listeners for 
other events, such as application errors, new requests, etc. 


Now we can try to complete the event registration; everything should 
work without problems. 


7.4 Validating the basic data 


Another very common point in every application is the validation of 
the data being registered. Until now, no verification of the incoming 
data in our system has been done. The first technique that can be 
employed is the use of HTMLD5 itself to perform this validation. 


1 <input type="text" id="name" name="name" 
value="" 
2 required="regquired"> 


As much as this approach is valid, it is never completely safe to 
leave the validation just on the side of the client. The HTML code is 


easily changeable through the tools provided by browsers. In order 
to improve the security of the validation, we will add some validation 
on the server side also. 


To facilitate this part, Play already has an integration attuned with the 
Java world specifications called Bean Validation. It already provides 
a validation mechanism based on annotations, which is widespread 
among programmers. Let's see some examples of validation in our 
model: 


1 import org.hibernate.validator.constraints.URL; 

2 

3 import play.data.validation.Constraints.Email; 

4 import 
play.data.validation.Constraints.Required; 


@Entity 
public class Conference { 


6 
7 
8 
9 @Id 
O @GeneratedValue 
1 private Integer id; 
2 @Email 
13 private String contactEmail; 

4 QEnumerated (EnumType.STRING) 

5 private ConferenceState state; 

6 @Column(columnDefinition = "text") 
7 private String description; 

8 GURL 

9 private String site; 
20 private String twitter; 
2 @Required 
Le private String name; 
23 private Calendar startDate; 
24 private Calendar endDate; 








Through the imports, you can see that the class is annotated with 
both annotations: from Hibernate Validator, which is the reference 
implementation of the specification; and with annotations of Play 
itself, which were created following the rules of Bean Validation. 
Below are some other useful annotations. 


e @Length: checks the size of a string. 

e @NotBlank: checks if the string is empty. It also checks if it is 
null or with no characters. 

e @SafeHTML: checks if the HTML passed by the user has any 
dangerous section. Common in systems that receive user inputs 
through rich editors. 


Now that the model is correctly annotated, it is necessary to perform 
the validation on the application controller. 





1 public static Result create() { 

2 Form<Conference> formFromRequest = 
conferenceForm. 

3 bindFromRequest () ; 

4 if (formFromRequest.hasErrors()) { 

3 return 
badRequest (views.html.conferences. 

6 new conference.render ()); 

7 } 

8 Conference conference = 
formFromRequest.get(); 

9 Ebean.save (conference); 

10 return 


redirect (routes.ConferencesController.list()); 
11 4 


The Form class already has a method to check for errors in our form. 
By the way, this method identifies any problem of data conversion, 
which was what was happening in the previous section. If we had 


used it, it would be possible to display a friendly message to the 
user. And if an error was found, the user would be directed to the 
same page as before. To continue working with the correct HTTP 
status, a “400” is returned indicating that the request had problems. 


One detail that needs attention now is the state of the registration 
page when a validation error occurs. The user returns to the 
registration page with the proper status, but the data that were 
previously entered by the user are not being displayed, so he can fill 
the problematic fields. To do so, it is necessary that the object of the 
type Form is available in view. This way you can retrieve the 
information entered by the user, as well as display the error 
messages. 


1 Form<Conference> formFromRequest = 


conferenceForm. 

2 bindFromRequest () ; 

3 if (formFromRequest.hasErrors()) { 

4 return badRegquest (views.html.conferences. 





new conterence.render (formFromRequest) ); 
6 } 


Right now the Play console will accuse a compilation error stating 
that the method render does not expect any argument. You need to 
add the parameter in view so that the utility class is recompiled. 


1 @(conferenceForm:Form[Conference] ) 

2 <html> 

3 <body> 

4 <form 
action="@routes.ConferencesController.create()" 

5 method="POST"> 
6 <input type="text" id="name" name="name" 


value="@conferenceForm. apply ( "name|") .fvaluel() "> 
8 <input type="text" id="contactEmail" 


name="CcContactEmail" 


9 
value=" Q@conferenceForm.apply ( "emaill") .jvaluel() "> 
10 <!-- other fields--> 
11 <input type="submit" value="New 
conference"> 
12 </form> 
13 </body> 
14 </html> 





The apply method returns an object of the type Field, and through it 
we have access to the value that was sent in the previous request. 
The same Field returns the validation problems associated with that 
field. By the way, this is one of the main reasons to use the form to 
display the values instead of an object of the type Evento because if 
we are losing the ability to catch errors at compile time—after all a 
string is passed as a parameter to the apply method—we gain an 
object that gives us access to specific information of each field. 
Below is an example of how you can catch the errors associated with 
a particular field. 


1 @(conferenceForm:Form[Conference] ) 

2 <html> 

3 <body> 

4 <form 
action="@routes.ConferencesController.create()" 

5 method="POST"> 

6 <input type="text" id="name" name="name" 

a 
value="@conferenceForm.apply ( "name|") .jvalue|() "> 

8 <div class="errors"> 

9 Qfor (error <- 
conferenceForn|.lapply|("nameļf") .errors|O) { 


K<|span 

style="color: red">@error.message ()</span> 
igi } 

12 </div> 
13 





<input type="text" id="contactEmail" 
name="contactEmail" 
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value="@conferenceForm.apply ( "emaill") .jvaluel() "> 
<!-- other fields--> 
18 <input type="submit" value="New 


conference"> 
19 </form> 
20 </body> 
21 </html> 





7.5 Html helpers to facilitate building the forms 


The errors method was used to recover all the errors related to the 
field nome. The process would be repeated to every other field in the 
form. That’s when a framework is most helpful in the life of a 
developer. If this work is repeated many times, there is no reason for 
the programmer to be in charge of this; the framework should handle 
it. And Play helps us by providing objects that already build the form 
fields in association with the object _Form_. See below the same 
form built using the HTML helpers. 


1 @(conferenceForm:Form[Conference] ) 
2 @import helper. | 
3 


4 <html> 
5 <body> 
@form(routes.ConferencesController.create() ) 


8 @inputText (conferenceForm ("name") ) 
@inputText (conferenceForm("contactEmail") ) 


10 
@textarea (conferenceForm("description") ) 





11 <select name="state"> 

12 @for (state <- 
ConferenceStateļ.values) | j 

13 <option value="@state.name"> 
14 @state.name 

15 </option> 

16 } 

17 </select> 

18 QinputText (conferenceForm("site")) 
19 @inputText (conferenceForm("twitter") ) 
20 <fieldset> 

21 <legend>Period</legend> 

22 

@inputDate (conferenceForm ("startDate") ) 

23 @inputDate (conferenceForm("endDate") ) 
24 </fieldset> 

25 <input type="submit" value="new 
conference"> 

26 

27 } 

28 </body> 

29 </html> 


Keep in mind that the code above will generate the HTML of the form 
for registering the conference. We have some important parts that 
must be analyzed. The first one is the static import of helper. The 
syntax with underline is from Scala, but the functionality is the same 
as Java’s static import. This helper package has several input 
templates that we can use. In the page of conference registration, 
we can use inputText, textArea, and inputDate to generate the HTML 
needed for each of the inputs. Below is a sample of the HTML 
generated by the Play helpers. 


1 <dl class=" " id="nome field"> 

2 <dt><label for="nome">name</label></dt> 
3 <dd> 

4 <input type="text" id="name" name="name" 


value="""> 

5 </dd> 

6 <dd class="info">...</dd> 
7 </dl> 


And in case of an error page: 


1 <dl class=" error" id="nome field"> 
2 <dt><label for="name">name</label></dt> 
3 <dd> 
4 <input type="text" id="name" name="name" 
value="" > 

</dd> 


<dd class="error">Required</dd> 
<dd class="info">This field is required</dd> 
</dl> 
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We no longer have to keep writing code to display validation errors 
associated with a field, nor do we need to fill in the value. The Play’s 
helper does it all for us. In a system with many forms, this is very 
important in order to ensure speed and efficiency when building 
these pages. The HTML generated is already based on templates 
from Play, and they can be altered to suit the layout pattern of the 
system. We will see more about this in a chapter exclusively on 
templates! 


7.6 Changing the validation messages 


Right now, when the user reaches the registration conference page, 
just below the "nome" field, it says "Required", informing us that this 
field is mandatory. There is a similar information for the email field, 
and so on. In general, we have to change those messages, as well 
as messages of validation errors, to adapt them to the customer 
needs. To accomplish these changes of the messages that are 


displayed in our application, there is the messages file that should 
be created in the conf folder. 


1 constraint.required = Please fill this field 
2 error.regquired = This field is required 


And where do these keys come from? There is a little bit of Bean 
Validation here mixed with a little of Play itself. The validation 
annotations defined by the framework follow the requests proposed 
by the specification. Let’s take a look at the annotation Required. 


@Target ({FIELD}) 
2 @Retention (RUNTIME) 
3 @Constraint (validatedBy = 
RequiredValidator.class) 
4 
@play.data.Form.Display (name="constraint.regquired" 


) = 


6 public static @interface Required { 
String message() default 
RequiredValidator.message; 
3 Class<?>[] groups() default {}; 
S Class<? extends Payload>[] payload() 
default {}; 
10 } 


In the midst of so much information in this annotation, we will focus 
only on what refers to the messages; everything else we leave to the 
section on customized validation. The message attribute defines the 
properties key that will be used when a validation error occurs; that 
is a requirement of the specification. However, the Bean Validation 
defines that the key of the messages should always come between 
{}, that is, instead of being error.required, it should be 
{error.required}. The decision to not use it was made by Play. The 
annotation *Display* receives the properties key regarding the alert 
message to the user. Therefore, we use the keys with those names. 
For any messages customization, just analyze these two details of 


the annotations and make the change in the message file. We will 
see more about internationalization in a chapter solely devoted to 
that topic. 


7.7 Creating a reusable validation 


A necessary validation for the conference registration is that the 
starting date is from the day of registration. For example, if a user is 
performing the registration on January 20, 2014, the date of 
registration will be from this day on. The annotation that is closest to 
this characteristic is Future, which comes by default in 
BeanvValidation. 


The problem with this annotation is that it only considers valid dates 
that comes after the day "today", and, because of this, the above 
scenario would not be accepted. As there is no annotation ready that 
fits this scenario, we will create our own. 


The first step is to create the annotation that will be used for our 
validation case. As it is necessary that today's date is valid, the 
name chosen is FromNow. 


@Target (value={ElementType. FIELD} ) 
2 @Retention (RetentionPolicy.RUNTIME) 
3 @Documented 
4 @play.data.Form. Display (name="error.fromNow") 
5 public @interface FromNow { 


String message() default 
"constraint. frowNow"; 


Class<?>[] groups() default { }; 


Class<? extends Payload>[] payload() default 


{ }y¥ 
12 } 


It is quite similar to the annotation Required, which was presented a 
little earlier in this chapter. The Display annotation was used to 
define the message key that presents the alert to the user, and it 
also has the attribute message, which has the key to be used to 
define the validation error message. The other two attributes, group 
and payload, have more specific details. The first one is to group 
possible validations; for example, the manager may forget to register 
the contact email, while this is mandatory for the other users. 
Payload is used to add a higher level of alert for certain validation 
errors, for example, a weak password into the database of a user. 


Now it is necessary to create a class that contains the validation rule 
itself. It is a common class that implements the interface 
ConstraintValidator. 


1 public class FromNowValidator 

2 implements 
ConstraintValidator<FromNow,Calendar> { 

2 
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4 private FutureValidatorForCalendar 
futureValidator = 

5 new 
FutureValidatorForCalendar(); 

6 

7 @Override 


8 public boolean isValid(Calendar date, 
9 ConstraintValidatorContext 
constraintValidatorContext) { 


10 if (date==null) return true; 

11 Calendar today = Calendar.getInstance(); 
12 return sameDay (today, date) 

13 |] futureValidator. 

14 isValid(date, 





constraintValidatorContext) ; 
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17 private boolean sameDay (Calendar today, 
Calendar date) { 





18 return today.get (Calendar.DAY OF MONTH) == 
date 
19 .get (Calendar .DAY OF MONTE) 
20 && today.get(Calendar.MONTH) == 
21 date.get (Calendar .MONTH) 
22 && today.get(Calendar.YEAR) == 
23 date.get (Calendar. YEAR) ; 
6 @Override 
/ 


public void initialize(FromNow fromNow) { 


CO 


WO 


} 
} 
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The isValid method contains a specific rule. Validations are usually 
very specific. Note that if the value of the date is null, the value is 
considered valid. If the user wants to forbid zero dates, he should 
use the NotNul/ annotation in conjunction with ours. To avoid 
rewriting a rule that checks if a day is after the other, the class 
Future ValidatorForCalendar is used from the Hibernate Validator 
itself, reusing a code that has already been written. The initialize 
method is used in case the annotation has extra attributes that can 
be used by the programmer to provide extra information on 
validation. A usual case is to pass the regex in the Pattern 
annotation. 


The last missing point is to make the binding between the annotation 
and the validation class. That’s why the annotation @Constraint_ 
exists, placed on top of the annotation that defines the custom 
validation. 














1 @Target (value={ElementType.FIELD}) 

2 @Retention (RetentionPolicy.RUNTIME) 

3 @Documented 

4 @Constraint (validatedBy=FromNowValidator.class) 
5 @play.data.Form. Display (name="error.FromNow") 

6 public @interface FromNow { 

g 

8 String message () default 
"constraint. ErowNow"; 

9 
LO Class<?>[] groups () default { }; 
11 
12 Class<? extends Payload>[] payload() default 
{ }; 
13 
14 
15 } 





To sum up, simply add the keys in the file messages. If a user 
enters an invalid beginning date, our validation will be used and will 
not let the process be completed. The annotation use is quite simple; 
just add it on top of the startDate attribute. 


1 @FromNow 
2 private Calendar startDate; 


7.8 Specific model validation 


One final point concerning the validation process is the verification of 
the time period that will be registered for the conference. The rule is 
simple: if the conference is only one day in duration, the beginning 
date is equal to the ending one. If it lasts longer, the ending date 
must come after the beginning date. This is another validation that 
does not exist by default, and, as we did the basic date validation, a 
customized annotation could be created. Just for trying another 


mechanism provided by Play, let’s go through another way to create 
a validation method within the class. 


It is possible to create a method called *validate* that returns a list of 
validation errors within its own class. In the case of validating a time 
period, see as follows: 


public class Conference { 
//rest of the code 


public List<ValidationError> validate() { 
ArrayList<ValidationError> errors = 
new ArrayList<ValidationError>() ; 
if (endDate == null) { 
this.endDate = (Calendar) 
artDate.clone(); 
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9 return null; 
10 } 
11 if ('endDate.after(startDate)) { 
12 errors.add ( 
13 new ValidationError("endDate", 
14 "The end must be greater than the 
beginning")); 
15 } 
LO 
Le return errors.isEmpty() ? null : errors; 
18 } 
19 } 





If the return is a list, Play understands that there are validation 
errors. Just to make it clear, if the return is not null (including the 
empty list), the framework considers that there are validation errors. 
The code is simple; only the time period rule is checked, and, if the 
ending date is not filled, it is equated to the beginning date. The 
class constructor ValidationError receives as arguments the name of 
the attribute being validated and the message. An important detail is 
that the validate method is only executed if the validations based on 


the annotations pass. An important reminder is that the name of the 
method must be validate, which is a convention imposed by Play. 


7.9 Conclusion 


This was a dense chapter. Maybe it's time to take a breath and 
review a little about what has been done before moving on. We saw 
a bit more about Evolutions as we had to change the table structure 
to add the fields related to dates. We also passed by a problem of 
conversion of types, which was resolved through the Play 
Formatters, which made us see a little more about how to extend the 
functionalities that come as default. Finally, we passed through 
several validation issues, which were resolved in all the ways that 
Play provides for us, programmers. 


CAPITULO 8: 
Uploading the conference image 


The last step to complete the conference registration is to send an 
image that represents the conference, a feature image. Uploading is 
a very common task, and Play already comes with basic support for 
handling this type of request. 


Let’s begin with the easy part, adding a new field in our registration 
form. 


1 le] (conferenceForm: Form[Conference] ) 
2 Cimport helper. 
3 <html> 

4 <body> 


a OTe ConferencesController.create(), 
6 ['lenct ype -> "multipart /ftorm-data"™) { 
7 <!--other fields--> 


a 
O 


@inputFile (conferenceForm("featureImage") ) 


9 <input type="submit" value="new 
conference"> 
10 } 
11 </body> 
12 </html> 


We did not do anything fancy here. We used the helper to build an 
input of the type File, and in addition, we passed a new parameter to 
the form method. The syntax-making use of the -> is the way to build 
Scala inputs for a HashMap. And this is the last parameter of form, a 
Hash with the properties we want to associate with the form. In this 
case we are saying that we will send the data with the Content-Type 
multipart/form-data, the most common way of submitting files 
through web forms. All the input helpers from Play can receive this 
Hash as the last argument. 


8.1 Dealing with upload at the Controller 


It is necessary now to deal with the uploaded file in the Controller 
method. First, you need to access the uploaded file. 


1 RegquestBody requestBody = request().body(); 

2 MultipartFormData body = 
requestBody.asMultipartFormData () ; 

3 FilePart filePart = 
body.getFile("featureImage") ; 

4 File featureImageUploaded = filePart.getFile(); 


RequestBody is able to access in various formats the data sent in 
the request. For example: 


e requestBody.asJson() 
e requestBody.asXml() 
e requestBody.asFormUrlEncoded() 


Everything will depend on how you send the data. Remember that 
here we are dealing with data from the browsers’ requests, however 
the client could be any application. 


Now that the file has been remounted on the server side, we just 
need to save it somewhere. Following the convention of Play, we can 
store it in the folder public/Aimages and, inside it, create another 
folder called feature_images. The final code would look something 
like the following: 


RequestBody requestBody = request().body(); 
MultipartFormData body = 
requestBody.asMultipartFormData () ; 
3 FilePart filePart = 
body.getFile("featureImage") ; 

File featureImageUploaded = filePart.getFile(); 
5 File newImage = new 
File("public/images/feature images", 


1 
1 
2 


6 System.currentTimeMillis()+ " " 
7 + 7 
featureImageUploaded.getFilename()); 

8 FileUtils.moveFile (featureImageUploaded, 
newlmage) ; 


The framework still lacks a plugin that helps save the file. Another 
detail that might be interesting is to have the option to send these 
images to S3, a storage service provided by Amazon and widely 
used around the world. Who knows if this may not be our plugin at 
the end of the book? Including Heroku, this is one of the possible 
places where we can perform the deploy of our application, which 
provides an implementation for it. The same can be found at the link 
https://devcenter.heroku.com/articles/using-amazon-s3-for-file- 


The Rails framework already has plugins that, besides saving the 
image that was submitted, also perform the treatment for them. 
Generally, this treatment is done with the ImageMagick tool, which 
must be installed locally in the machine. 


8.2 Integrating the upload with saving the 
conference 


Part of the chapter was reserved only for the uploading because the 
code is somewhat extensive. Now it is time to integrate the snippets 
seen above with the existing code in our application. The first step is 
to separate the process of building and saving the highlight in a 
private method. This way, we keep a minimum of readability in the 
create method. 


1 public class ConferencesController extends 
Controller { 
2 //rest of the code 


o 


private static File saveFeaturelImage () 
throws IOException { 
RequestBody requestBody = request().body(); 


OY Ow 


7 MultipartFormData body = 
requestBody.asMultipartFormData () ; 

8 FilePart filePart = 
body.getFile("featureImage") ; 

9 File featureImageUploaded = 
filePart.getFile(); 
10 File newImage = new 
File("public/images/feature images", 
11 System.currentTimeMillis()+ 
12 + filePart.getFilename())j; 
13 FileUtils.moveFile (featureImageUploaded, 
newlmage) ; 
14 return newlmage; 
15 } 
I7 } 





Now just invoke this method during the process of creating an event. 


1 public class ConferencesController extends 
Controller { 

2 public static Result create() throws 
IOException { 


3 Form<Conference> formFromRequest = 
conferenceForm 

4 .bindFromRequest (); 

5 if (formFromRequest.hasErrors()) { 

6 return badRequest (views.html. 

7 conferences 

8 





New conference.render (formFromRequest)); 
2 } 
10 Conference conference = 


formFromRequest.get(); 

11 File featureImage = saveFeaturelImage(); 
12 //using assets because is the configured 
route in your 

13 //routes file 

14 conference.setFeatureImageSrc 








("/assets/images/feature images/"+featureImage.get 
Name ()); 





16 try { 

Ly Ebean. save (conference); 
18 } catch (Exception e) { 

19 featureImage.delete(); 
20 } 

21 return 


redirect (routes.ConferencesController.list()); 
22 } 

23 

2a 4 


There are two details that should get noticed. We saved on the 
database only the name of the image instead of the binary itself. The 
idea is that we can change that easily and keep these images on 
Amazon S3. The second is that, if you have problems during the 
conference being saved, the image associated with it is also deleted. 
This is an important step so we don't remain with many images that 
do not actually belong to any conference. 


To complete this part, we need to add the attribute featurelmageSrc 
to the Conference class and, in addition, create the new evolution. 
Below is the evolution file. As this is our second evolution, for now 
let's call it 3.sql. 


1 # --- !Ups 


NO 


3 alter table conference add feature image src 
varchar (255); 


Oy O1 


CO ~ 


# --- !Downs 


O 


10 alter table conference drop column 
feature image src; 


As usual, the first time the application is accessed, Play will detect a 
new evolution and request permission for the same to be performed. 


8.3 Conclusion 


In this chapter, we have seen how to perform uploads using Play. 
The code is somewhat extensive, but it will be resolved with the 
creation of a plugin at the end of the book. At this point, you already 
have enough information to begin developing your new application. 
Do not waste time; practice is important for the assimilation of the 
content. 


CAPITULO 9: 
Sending emails asynchronously 


Right now, any conference registered in Agendatech is being 
displayed in the main list. But there is a problem: if some malicious 
registration is performed, due to the lack of an approval process, the 
same will be displayed on the site, injuring a bit of our reputation. 
The idea now is to add the flow of approved events. 


The first thing to be done is to add an attribute indicating whether the 
event is approved or not. 


@Entity 
public class Conference { 


1 
2 
3 
4 //other attributes 

5 private boolean approved; 
6 

1 

8 


//other methods 
} 


It is also necessary to add another evolution. 


1 # === !Ups 

2 

3 alter table conference add approved tinyint 
default 0 

4 


5 
6 
7 
8 # --- !Downs 
9 
0 


10 alter table conference drop column approved; 


Note that, purposely, the default value of the column has been left 
approved with zero. Initially, no event is approved. We will have to do 
it manually. To enable this approval, a page with a list of all events 
will be created, separated between approved and unapproved. As 
we have done during the book, we will begin by the page and then 
implement our controller. The same will be in the 
views.conferences.admin package. This way, the administration 
pages are separate from the pages of regular conferences. 


1 
@ (nonApproved:List[Conference],approved:List[Confe 
rence | ) 











2 <html> 
3 <body> 
4 <h3>Non approved</h3> 
5 <ul> 
6 @for (conference <- nonApproved)) | k 
7 k|Li>@conference.getName () - 
8 <a href="">Approve</a> 
9 </li> 
10 } 
11 </ul> 
12 <hr/> 
13 <h3>Approved</h3> 
14 <ul> 
L5 @for (conference <- approved) | k 
16 klLi>@conference.getName ()</1i> 
17 } 
18 </ul> 
19 </body> 
20 </html> 


In a while, we will add the action of approval and configure it in the 
routes file. That’s why we left that text in the href attribute of the link. 
No wasting time, let's just create the action that loads all registered 
events. To separate the management classes, we will create it in the 
controllers.admin package. 


public class AdminConferencesController 
extends Controller { 


1 
2 
3 
4 public static Result all() { 

5 List<Conference> approved = Ebean. 

6 find(Conference.class) .where() 

7 .eq("approved", true) .findList(); 

8 List<Conference> nonApproved = Ebean. 

9 find (Conference.class) .where() 

0 .eq("approved", false) .findList(); 
1 return ok(views.html.conferences.admin. 
1 

3 

4 


l conferences.render (monApproved, approved) ) ; 


} 








} 


We have left the database access code mixed in the controller 
because we had only called the method that was saving and listing 
everything in the database. Now that there is a query with condition, 
it's time to put this logic within a specialized class. 


1 package persistence; 

2 

3 public class Conferences { 

4 

5 public static List<Conference> 
approved (boolean status) { 


6 return Ebean.find(Conference.class) 
7 .where ().eq("approved", status) 

8 .findList(); 

9 } 
10 } 


This class implements a Design Pattern known as DAO. We can 
change the code to reflect this change. 


1 public class AdminConferencesController 
2 extends Controller { 


public static Result all() { 

5 List<Conference> approved = Conferences 
-approved (true) ; 

List<Conference> nonApproved = Conferences 
.approved (false); 

9 return ok(views.html.conferences.admin. 

10 

all conferences.render (nonApproved, approved) ) ; 

11 } 

12 } 


OY 


CO 





The code is now much more readable. We will keep good judgment 
about whether or not to create methods in DAO. The basic rule will 
be that when you really have a logical query, with conditions or other 
characteristics, the code will be isolated. If it is only one invocation 
for a save Or update, the snippet will be maintained in the 
controller. Dear reader, remember that putting the code in the right 
place is a complicated task. If you disagree with this approach, feel 
free to try new strategies. 


Now we just need to add the access URL in the route file, and in this 
way, the functionality will be released to the Agendatech 
administrator. 


GET 
/conferences/admin 


gy) BD H 


Y 


controllers.admin.AdminConferencesController.all () 


9.1 Approving the conference 


On the administration page we left a link, purposefully without the 
href, which should point to the URL of approval. To begin to address 
this problem, lets create the action responsible for dealing with this 
functionality. 


1 public class AdminConferencesController extends 
Controller { 
2 //other actions 


4 public static Result approve (Integer id){ 
5 Conference conference = 
Ebean.find(Conference.class,id); 





6 conference.setApproved (true) ; 
7 Ebean.update (conference); 
8 return redirect (controllers.admin 


9 
.routes.AdminConferencesController.all()); 
10 } 


11 } 





The logic itself has nothing fancy. The detail that deserves attention 
is that, for the first time, the action receives a parameter. After all, we 
need the conference id so we can make the approval process. This 
setting should be done in the routes file. 


1 GET /conference/admin/approve/:id 
controllers.admin.AdminConferencesController.appro 
ve (id: Integer) 


Note that we use the notation :variable. Here we are saying that, in 
fact, a part of the URL is composed of a parameter. The same 
variable name should be used when declaring the action parameter 
in the route, which is how Play makes the binding between what is 
being passed in the URL and the position that should be passed to 
the action. 


With the approval functionality momentarily completed, it is 
necessary to carry out the change in the view of the conference 
administration so the link can point to the correct place. 


J 
@ (nonApproved:List[Conference],approved:List[Confe 


rence | ) 














2 <html> 
3 <body> 
4 <h3>Non approved</h3> 
5 <ul> 
6 @for(conference <- nonApproved))| lt 
7 klLi>@conference.getName () - 
8 <a 
9 
href="@admin. routes .AdminConferencesController. 
10 approve (conference.getId())"> 
11 Approve 
12 </a> 
13 </li> 
14 } 
15 </ul> 
16 <hr/> 
17 <h3>Approved</h3> 
18 <ul> 
19 @for (conference <- approved) | k 
20 k|Li>@conference.getName ()</1i> 
21 } 
22 </ul> 
23 </body> 
24 </html> 


An important detail to notice is that we had to access the routes 
class by putting the package admin in front. By default, it only 
matters to Play the controllers package to the view, and, as there is 
the automatically generated class called routes within it, we were 
accessing it without any problems. Now that we created a new 
package, Play has generated a new routes class within the 
controllers.admin package, and so we had to slightly modify our way 
of accessing it. Just for clarification, the structure generated is as 
follows: 


Y jp agendatech-en 
> aS app 
P E test 
¥ £ classes_managed - /Users/albertoluizsouza/z 
b H (default package) 
¥ 3 controllers 
H £4 javascript 
>» £6 ref 
b wp ReverseAdminConferencesController. 
P wp foutes.class 
b £4 javascript 
» H ref 
b mh ReverseAssets.class 
b p ReverseConferencesController.class 
P wp Foutes.class 
b H views.html.conferences 
Fig.9.1 


9.2 Composing URLs with parameters 


Going back a bit, the composition of a URL with parameters is quite 
flexible in Play. Let's take a better look at it. In the previous example, 
we specified that it was necessary to pass the conference id as 
being approved as a parameter. 


1 GET /conference/admin/approve/:id 


controllers.admin.AdminConferencesController.appro 
ve (id: Integer) 


If a non-numeric parameter passed, Play would return the status 
400, also known as Bad Request, indicating that the request was 
made with invalid information. It can deduct it as the action 
parameter receives a Long. Thinking a bit further on this issue, in 
fact the request was made to the wrong URL! As we have no 
intention of treating alphanumeric ids, we add a rule in our route for 
Play to return 404, stating that the URL requested by the user does 
not exist. 


1 GET /conference/admin/approve/:id<[0-9]+> 


controllers.admin.AdminConferencesController.appro 
ve (id: Integer) 


Regular expressions are supported in the routes. This way, the 
programmer is free to add some specific rules to make the job of 
those who try to pass invalid arguments in the URLs more difficult. 


Regular expressions tend to be very complex if used for a very 
complicated parameters prevention. Remember to add only the 
basic ones so we will get a minimum guarantee without 
compromising the maintainability of the routes much. 


Conflict between routes and default values 


Another functionality that has not yet been implemented is the 
visualization of the event details. We will leave the code itself for a 
later time, but let's think a bit about how it would be the route to this 


page. 


GET /conferences/:id 
2 controllers.ConferencesController.show (id: 


Integer) 





4 GET /conferences/new 
controllers.ConferencesController.form() 


We did as usual, add the call to a possible Controller action in our 
file. The detail that can surprise us here is that, if a user accesses 
the address /conferences/new, the first declared route will serve as 
resolution for the requested URL. Play will replace the parameter :id 
by the word new, passed by the user, and it will generate an error 
because the method expects an Integer as argument. 


This is a classic problem in files of routes settings. The first one 
found, which matches with the passed URL, is used to invoke the 
action. A simple way to solve it is to reverse the order of the routes. 
The detail the programmer has to be aware of is that, perhaps, the 
system contains so many routes that arranging them in a way that 
priority is respected may become a rather complex task. 


Another way to alleviate the problem of priorities is by using regular 
expressions in routes. With the types of values defined, Play will 
search the route whose parameter is replaceable by regex. For 
example: 


GET /conferences/:id<[0-9]+> 
2 controllers.ConferencesController.show (id: 
Integer) 


4 GET /conferences/new 
controllers.ConferencesController.form() 





We are ensuring that the merged id in the URL has to be a number. 
If Play verifies the access to the address `/conferences/new`, it will 
automatically skip the first route. 


9.3 Sending email 


Returning to the last functionality implemented, the approval of 
conferences, there is an important detail missing. As it stands now, 
we can begin to forget that the conferences are being registered, as 
we are not advised on any new registration. To improve this, let’s add 
an alert with an email sent for every new conference. 


As we don’t want to waste time implementing all the functionality of 
sending emails, something very common in applications, we will use 
a ready plugin. To find a list of plugins endorsed by Typesafe, the 
company that maintains Play, access 
‘https://github.com/typesafehub/play-plugins’. We will use the plugin 
called mailer, which already has an implementation for sending 
emails with settings that can vary depending on the environment, 
besides already having a fake Mailer, which facilitates our tests. 


To add the plugin to the project, just add the dependencies in 
build.sbt responsible for the configuration of modules of our project. 





1 libraryDependencies ++= Seq ( 
2 #outras depedencias, 
3 "javax.mail" % "mail" % "1.4.1", 

4 "com.typesafe.play.plugins" %% "play-plugins- 
mailer" % "2.3.0" 


cm 


Let's reach now the most interesting part, which is sending the email 
itself. Settings in external files are at the end of the section. In the 
action that registers the conference, in addition to changing the 
status of the conference, we have to send the email to the system 
administrator. 


1 public static Result create() throws IOException 
{ 

2 //rest of the code 

3 EmailsSender.notifyNew (conference) ; 


4 return 
redirect (routes.ConferencesController.list()); 


The logic has been purposely left from sending in another class. 
Remember that its action ideally should only invoke the steps 
responsible to implement its business rule. The class EmailsSender 
looks like this: 


1 public class EmailsSender { 

3 

4 public static void notifyNew (Conference 
conference) { 

5 MailerAPI mail = play.Play 
-application().plugin(MailerPlugin.class) .email(); 


7 
/ 


mail.setSubject ("mailer"); 
8 
mail.addFrom("registration@agendatech.com.br") ; 








9 mail.addRecipient ("admin- 
agendatech@gmail.com") ; 
10 Html render = views.html.email 
11 .new_conference.render (conference); 
12 mail.sendHtml (render.body()); 
13 } 
14 } 





The code is self explanatory, but a few points are worth mentioning. 
Whenever you need to load a plugin by Play, a factory method called 
plugin will be used, which receives as a parameter a class that is 
the entry point for the use of the plugin. We will basically do it when 
implementing the Upload plugin. 


Another very interesting point is that we externalized the HTML of 
sending email in a common view. Pay attention on these snippets: 


1 Html render = views.html.email 


2 sew conference.render (conference); 





3 mail.sendHtml (render.body()); 


As our view is compiled, we can access it from anywhere in our 
code. So we basically did what we are used to doing in controllers: 
we called the render method, passing the parameter it expects, and 
then we took the body generated. Very simple and already supported 
by the framework! This way it is very easy to create any template for 
sending emails to any system that will be further developed. 


Setting up the mailer 


It is necessary to perform the basic configuration for sending emails, 
such as port and login. All these settings should be in the file 
application.conf, which has the default settings of the application. 


1 #smtp.host (mandatory) 

2 #smtp.port (defaults to 25) 
3 #smtp.ssl (defaults to no) 
4 #smtp.tls (defaults to no) 
5 #smtp.user (optional) 

6 #smtp.password (optional) 








Everything is commented because these settings depend on the 
email service that is being used by the application. Another important 
setting, at least for the testing period of the application, is that we do 
not want to send real emails. We just want to perform a simulation. 
For doing so, let’s add a configuration line: 


| smtp.mock = true 
Okay, that's enough for the mailer to choose a fake implementation. 


One final point to be set is the loading order of the plugin. The idea is 
that you can choose, for example, if you want it to be loaded before 
or after loading the default settings of the framework. Another 
situation could be in relation to a dependency with another plugin. 


To do this, the file named play.plugins will be created. 


1 1500:com.typesafe.plugin.CommonsMailerPlugin 


For example, the inclusion of 1500 guarantees that it runs after the 
settings of the framework core but before GlobalPlugin, which is 
responsible for calling the Global class, which was created to make 
the Formatter registration of dates. Within the framework itself, there 
is a configuration file of plugins. 


1 100:play.api.il8n.DefaultMessagesPlugin 
2 100:play.core.RouterCacheLifecycle 

3 1000:play.api.libs.concurrent.AkkaPlugin 
4 10000:play.api.GlobalPlugin 


This snippet can be found in the repository of the project itself, 





9.4 Problems when running synchronous code 


Now that the email can be sent after the registration of a new 
conference, we fall into a new problem. At this very moment, if our 
application receives a bunch of requests and the mail server is a little 
slow for any given reason, we may begin to generate a bottleneck. 
This situation can happen with other applications. Imagine an E- 
commerce system where the gateway of payments is kind of slow. If 
many people want to buy a product on sale, the site may begin 
getting slow because this integration point is funneling all requests in 
the system. 


In programming, this situation where a code is stuck waiting for the 
other to finish is called synchronous processing. And it is often the 
root of many problems in our code. Generally any transaction 
involving IO, such as access to the database, web services, and 
sending emails, are points that make the system go into bottleneck 
situations. 


Default working model of the servers 


Most servers that we are accustomed to using to develop Java 
applications work in the 1 thread per request model. That is, if your 
action performs a time-consuming process, other application clients 
may begin to suffer a reflection of your slowness. 


Servers like Jetty and Tomcat already have settings that allow you to 
change some of this working model. And the new generation of Web 
servers, like Grizzly and Undertow, were already built to be used by 
applications that do not want to hinder all the processing while a 
heavy task is being performed. This is known as asynchronous 
model. 


The big problem here is that the Servlet API is not designed to work 
that way. So it's pointless for the servers to provide all the necessary 
infrastructure if the APIs cannot take advantage of it. The problem 
was not solved even with the addition of support to the execution of 
asynchronous code, included in the Servlets 3 specification. 


Various projects in the Java world work based on a class called 
ThreadLocal, which is basically a map of Thread (a request) to an 
object. When a new asynchronous context is initiated, new Threads 
are generated and consequently this map is lost. The frameworks 
have been trying to solve it, and progress can already be seen in 
Spring and Weld, but even though it is just an adjustment and not a 
model, a fix has been planned since the creation of the API. 


The same happens in the world Ruby with the Thin server, for 
instance. The infrastructure is based on asynchronous events, but if 
the libs used in the projects don’t make use of this, such infra is 
worthless. 


9.5 Native support for asynchronous execution 


In Play, unlike the cases cited above, API and infrastructure are in 
perfect harmony. This is one of the advantages of Play not using a 
server that follows the specification of Servlets. On the one hand, it 
loses heavily in standardization, but on the other, the gain in 
integration is rewarding. The server used by the framework is based 
on Netty(http://netty.io), which was created with the idea of 
supporting multiple protocols, and among them is HTTP. As it is 
completely based on events, usually it means that it works 
asynchronously, perfectly fit in to what Play is looking for. 





To complete the support to the execution of asynchronous code 
within an action, Play is also based on another project, called AKKA 
(http://akka.io/). This library allows the communication between the 
parts of the system to be done through messages. Basically, instead 
of invoking a method on an object that you know, it simply passes 
the parameters to an AKKA method, and it then passes on to its 
object. The advantage is that the AKKA can run this code in a 
separate thread, control the simultaneous access, deal with 
synchronization problems, etc. More details about the whole theory 
behind AKKA can be found on the website (http://akka.io/) and on 
the excellent course (https://www.coursera.org/course/reactive) 
provided by Coursera. 


Making an action asynchronous 


Given all this context, let’s begin to see how our approval code 
would run in an asynchronous way. 


1 Promise<Void> sendingEmail = 


return null; 


2 Promise.promise (new Function0<Void>() { 
3 @Override 

4 public Void apply() throws Throwable { 
5 EmailsSender.notifyNew(conference); 


Do not be scared; there is a lot going on in the code above. At this 
time, the most important thing is to understand is that the object of 
the type Promise represents an intention to execute some code. It is 
very similar to java.util.concurrent.Callable, present in the futures 
API of Java. If we want to be quite honest, this is the API being used 
there under the hood; the advantage is that you do not need to deal 
with the infrastructure details of this code. 


The code that should be run is passed through an anonymous class, 
called Function0, which is in the package play.libs.F. And the 
typing is to say that our code will generate some return, and as we 
only want to send the email, we will use the utility class Void, which 
allows us to return null within our method. 


Now that we have created the intention, we need to tell Play what we 
want to do when this code is executed. 


Promise<Result> result = sendingEmail 
.map (new Function<Void, Result>() { 
@Override 


public Result apply(Void nada) throws 
xception { 
k return 
redirect (routes.ConferencesController.list()); 
7 p; 


Ja EG Aa w N e 


Another snippet that’s a bit more complicated. The anonymous 
classes make everything get a little harder. Play is already prepared 
for Java8, and you can switch these anonymous classes for 
Lambdas. 


The method map is responsible for picking up the return of the 
execution of our Promise,so the first typing with Void generates a 
new promise, in this case with the intention to perform a redirect to 
the event listing on the home page of the application. That’s why the 
second parameter of typing is the Result. The class Function is 
also in the package java.libs.F. 


Now we just need to say that the return of our action is not a Result 
but a Promise<Result>. 





1 public static Promise<Result> create () 
2 throws IOException { 
3 //rest of the code 
4 
5 Promise<Void> sendingEmail = Promise 
6 .promise (new Function0O<Void>() { 
7 @Override 
8 public Void apply() throws Throwable { 
9 EmailsSender.notifyNew (conference) ; 
10 return null; 
11 } 
12 ree 
13 
14 Promise<Result> result = sendingEmail 
15 .map (new Function<Void, Result>() { 
16 @Override 
17 public Result apply(Void nada) throws 
Exception { 
18 return redirect (routes 
19 .ConferencesController.list()); 
20 } 
21 }); 
22 
23 return result; 
24 } 


This way, Play already knows that, while this Promise is not fulfilled, 
it can handle new requests, improving the system scalability. 


The access code to the database was purposely left outside 
Promise. It is the programmer's responsibility to know what are the 
bottlenecks of the system. A Promise could have been made to save 
in the database, so the map could have been used to generate 
another to send the email, and finally, a third Promise could be 


generated to return the Result. The composition would depend on 
the needs of the system. Have fun! 


9.6 Conclusion 


In this chapter we have seen a little of how to use a plugin for a 
routine task, but the most important is that we explored the idea of 
running asynchronous code. This is a functionality that should be 
explored in depth because the gains in scalability are valuable. 
Asynchronous code and Cache, subjects of the next chapter, are the 
major characters in the most famous systems around the world. 


CAPITULO 10: 
Caching the action results 


Listing and viewing Agendatech conferences are probably the 
functionalities (together with the registration part) more frequently 
accessed in the site. The fundamental difference is that, in the 
listing, we are loading various events all the time, while in 
registration only one form is exhibited, basically with no dynamic 
information. In the previous chapter we discussed how the 
performance of asynchronous tasks may help on the system 
scalability. Another point that can help both scalability and 
performance is not to keep accessing the database every time in 
order to retrieve the necessary information. 


Let's focus on the listing. As many conferences are registered, this 
number may approach 5 in one day, based on the previous 
experience with other technology conferences’ sites. Based on this 
principle, the listing that is displayed to a user at this time will 
probably not differ from the list that will be displayed to another user 
in the next ten minutes. Based on this analysis, which could be more 
extensive depending on the complexity of the application, we can 
keep in memory the HTML generated in the listing of conferences 
and use it during a specific time for all users that access the 
application, instead of building the page every time. This technique is 
known as Cache and can be applied to any type of data reading in 
your application, which does not always need to be the latest. 


10.1 Beginning with cache at Play 


Using the Play API cache is very simple. There is already a class 
called Cache that allows us to interact with the cache 
implementation used by the framework. For the curious ones, 
EhCache is used as default implementation. What we want is to 
save the result generated for the event listing. 


1 public static Result list() { 
2 Status result; 


3 if (Cache.get ("home") == null) { 
4 result = 


ok(views.html.conferences.list.render 
(Conferences.approved (true) ) ); 
6 int oneHourInSecons = 3600; 
Cache.set ("home", result, oneHourInSecons) ; 
8 } 


a A 


tO return (Result) Cache.get ("home"); 


Usually, we work with the object of the type Result; the only work is 
to check if it is already in the Cache, and if not, just add it. The first 
parameter of the set method is the key you want to associate with 
the entry being added to the cache. This way, you can retrieve this 
object from anywhere in the application. The last parameter indicates 
the time period that you want to keep the information cached, such 
value in seconds. Just as it was decided to cache the entire result, 
you could decide to cache only the return of the listing or also the 
view of the event detail. 


A point that we can think of here is the relationship between placing 
an object in the cache and the business rule being executed. Realize 
that we are mixing infrastructure details with the specific logic of the 
application. Still more, perhaps the cache limit has been reached, 
and the cache chooses to put part of the data in the disk to free up 
memory. Linking with the previous chapter, any write operation could 
be performed asynchronously, and, lucky for us, Play already comes 
with support ready to add the return of our action to the cache 
asynchronously. 


Facilitating the work with @Cache 


The action of advising Play that we wish the return of the action to 
remain in the cache is quite simple. 


1 @Cached (key="home", duration=3600) 

2 public static Result list() { 

3 return ok(views.html.conferences. 

4 list.render (Conferences.approved (true) )); 
5 


} 


Just for curiosity, lets take a look at how Play implemented the code 
that adds to the cache the return of the action. 


1 public class CachedAction extends 
Action<Cached> { 


2 

3 public F.Promise<SimpleResult> call(Context 
ctx) { 

4 try { 

5 final String key = 
configuration. key(); 

6 final Integer duration = 
configuration 

7 .duration(); 

8 SimpleResult result = 


(SimpleResult) Cache.get (key); 
F.Promise<SimpleResult> promise; 

0 if(result == null) { 

1 promise = delegate.call (ctx); 
12 promise.onRedeem 

3 (new F.Callback<SimpleResult> () 


WO 


4 @Override 

ie) public void invoke 
6 (SimpleResult 
i 


throws Throwable { 
Cache.set (key, 
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19 SimpleResult, 
duration); 


20 i 

21 }) 

22 } else { 

23 promise = 
F.Promise.pure (result); 

24 } 

25 return promise; 


) 
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2 } catch (RuntimeException e) { 

2 throw e; 

2 } catch (Throwable t) { 

29 throw new RuntimeException (t); 
30 } 

31 } 

32 

334 


It is not necessary to understand all the code at this time. The most 
important thing is to see that it puts the return in the cache using the 
Promise API that we studied in the previous chapter. Therefore, it 
does not block the application while writing in the cache. 


10.2 Invalidating the cache programmatically 


In general, when the expiration time of the cache has been decided, 
a basic analysis had been done regarding the data updates. For 
example, in Agendatech there is no problem if a new conference 
takes an hour to appear in our listing. Now, if the conference that 
was registered had paid to appear firstly, it might be important to 
invalidate the cache and retrieve the new listing. 


Because of this kind of situation, it is important to be able to 
invalidate any entry in the cache programmatically. We will isolate 
this rule in a controller and will use the same Cache class. 


public class CacheController extends Controller { 
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public static Result invalidate () { 
String key = 
equest () .getQueryString ("key"); 
Cache. remove (key); 
return ok(); 
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} 


Note that it does not have anything fancy. It receives a key as a 
parameter and removes from the cache the input associated with it. 
Our return is also very simple, it just uses the ok without parameter 
to indicate that we want to return the status 200. As usual, we have 
to add the URL associated with that action in the routes file. 


GET /cache/invalidate 
controllers.admin.CacheController.invalidate () 
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10.3 Take care with the type of cache you want 


The @cache keeps the return of your action regardless of which 
user has accessed the system. If you have a system where the 
cached page displays the name of a user logged in or something 
similar, the application may end up showing the page with the name 
of the user to someone else. Usually the use of this type of cache is 
most applicable to pages that have nothing to do with the user. 


Another approach would be to perform the cache by 
programmatically associating a user id in the key, but in this way, you 
could end up with a number of entries directly proportional to the 
number of logged in users. Therefore, think carefully before adding 
any page cache. 


10.4 Conclusion 


The use of caching can greatly help the application by improving 
both the response time to a user (performance) and maintaining this 
response time for multiple users (scalability). As the use of the API is 
very simple, attention should be given as to what data will be chosen 
to remain in the cache. 


Think about the possibility of the data being left with an old version to 
the user, the time they should survive in the cache, and if this 
information is general or specific to a user. 


Already thinking about the upcoming functionalities, you may have 
noticed that we have some parts that should only be available to 
system administrators. In the next chapter, we will see how Play 
helps us when we have to implement an authentication system. 


CAPITULO 11: 
Protecting the system 


Agendatech already brings some clearly administrative functionalities, such 
as Cleaning the cache and approving new conferences. The idea now is to 
protect the access to these functionalities by using an authentication 
system. 


11.1 Performing login 


Let’s begin building the process of authentication. First of all, as we have 
been doing throughout the book, we will create a view with the user login 
form. 








1 @(userForm:DynamicForm) 

2 Qimport helper. 

3 <html> 

4 <body> 

5 

6 @if(userForm.hasGlobalErrors) { 

7 <p class="error"> 

8 @userForm.globalError.message 

9 </p> 

10 } 

11 

13 @form(routes.LoginController.login()) { 
14 

15 @inputText (userForm("email") ) 

16 @inputPassword(userForm("password") ) 
17 <input type="submit" value="Login"> 
O 

19 } 
20 </body> 
21 </html> 


A different technique used to build this form was that—instead of using a 
Form[T], useful when we have forms related with more complex objects—we 
will utilize a DynamicForm. This class is more interesting when the form is 


simple, just like this one for login. Note that the use of helpers stays the 
same. The only difference is that instead of having an object from your 
model behind the Form, there is a Map with information to be displayed. 
Another solution that could eventually be adopted by more purist 
programmers would be the creation of a Login class just to contain the 
authentication data. Such a technique could be more interesting when you 
need the data from this form in more than one place in your application or if 
it really is a more complex form that, for example, may require validation 
rules. 


The form points to an action called login at the controller called 
LoginController. Let’s look over this implementation. 


1 public class LoginController extends Controller { 
3 private static DynamicForm form = Form.form(); 


4 
5 public static Result login() { 











6 Form<Dynamic> requestForm = 

form. bindFromRequest () ; 
7 String email = requestForm.data().get ("email"); 
8 String senha = 


requestForm.data().get ("password") ; 


oO 











10 User user = Users.findBy(email, 

11 Crypt.shal(senha)); 

13 if(user != null) { 

14 return 

15 redirect (controllers.admin.routes 

16 .AdminConferencesController.all()); 
uy } 

18 

19 

20 DynamicForm errorForm = 
form.fill(requestForm.data()); 

21 errorForm.reject ("Login/password invalid"); 
22 return 


forbidden (views. html.login.render (errorForm) ) ; 
25 } 
24 } 


There are many things going on in this action; let's start with what has 
already been reviewed. The DynamicForm is used to retrieve the values 
coming from the request. Note that the same method bindFromRequest is 
used, and it returns a Form[Dynamic] rather than a form linked to a class of 
its domain. Through it, we can retrieve the values passed as parameter. 
Apparently, nothing too complicated. 


The second part has to do with the realization of the user login into the 
application. The interesting thing is that there is nothing you would not be 
able to do yourself. The class Users concentrates the logic of the user 
verification on the database, as well as the class Conferences. Besides it, 
we need a class that represents the User. Following the convention, it will be 
created in the package models. 











1 @Entity 
2 public class User { 
3 
4 @Id 
5 private String email; 
6 private String password; 
7 
8 [** 
9 * @deprecated just for ebean 
10 *7/ 
11 Deprecated 
T2 public User() { 
13 } 
14 
15 public User (String email, String password) { 
16 this.email = email; 
17 this.password = password; 
18 } 
19 
20 //getters and setters 
21 } 


And now, the class Users: 


1 public class Users { 
p) 


3 public static User findBy (String email, String 
password) { 


4 User user = Ebean.find(User.class) 

5 .where().eq("email", email) 

6 .eq("password", password) .findUnique(); 
return user; 


1 
11 } 
#HHH No wasting time with subjects already studied. 


We have a new model class, which should be mapped into the database. 
Remember to create an evolution to represent this step, just like we have to 
set up, in the routes, the route for the action login. 


Some design 


Let’s get back to the snippet where we check if a user has been returned or 
not. 


User user = Users.findBy(email, 
Crypt.shal (password) ); 


if(user != null) { 
return redirect (controllers.admin 
.routes.AdminConferencesController.all()); 
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} 


This is a very common implementation when a method may return an object 
or not. The problem is that this is not clear in the method signature. The 
method returns a user, and the programmer may be tempted to use the 
object directly. Usually to find out if the return can be null or not, it is 
necessary to verify the implementation of the method. This type of situation 
is what leads us to receive in every project some NullPointerException. It 
is one of the most basic exceptions, regardless of the type of project, but we 
always end up by receiving it. 


In order to reduce the chance of this happening, we can make it clear in the 
method return that perhaps a user may not be found. 


1 public static Option<User> findBy(String email, 
String password) 


User user = Ebean.find(User.class) 
4 .where().eq("email", email) 
5 .eq("password", password) .findUnique(); 


if (user==null) { 


8 return Option.<User>None(); 
9 } 

10 return Option.Some (user) ; 

11 

12 } 


The return of the type Option does exactly this: it makes it clear that a user 
might be returned. The Option interface has two implementations: Some 
and None. As the names suggest, the first one indicates that something will 
be returned, and the second one, the opposite. This class is in the package 
play.libs. 


Now, in the action, we have to change the way we interact with the object. 





1 Option<User> possibleUser = Users.findBy (email, 
2 Crypt.shal (senha)); 

3 

4 1f(possibleUser.isDefined()) { 

Ə return 


redirect (controllers.admin 
.routes.AdminConferencesController.all()); 
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} 


Note that the programmer cannot use the user methods directly. He will 
always have to go through the Option, which is making it clear that perhaps 
no user exists. If an object is defined, it is sufficient to invoke the method 
get. The get invocation in an Option that does not have a definite object will 
throw an exception IllegalStateException, indicating that there is no value 
to be retrieved. 


Execution exception 


[Il legalStateException: No value] 


In /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/app/controllers/LoginController.java at line 25. 





Option<User> possibleUser = Users.findByCemail, 


Crypt .shal(senha)); 


| 25| System.out.printlnCpossibleUser.get()); 
ifCpossibleUser.isDefined()){ 


redirect(controllers.admin. routes .AdminConferencesController.all()); 


Another type of Result 


To sum up the last part of our action, we will use the forbidden method to 
indicate that the user has no access to the system. This helper builds an 
object of the type Result with the status 403. It is always interesting to return 
the right status for each situation; this way the client application can make 
better decisions about the returns of the actions. 


11.2 Restricting access 


The users are already being logged in, but the problem of liberated access 
still persists. Any user may point to the URL that is in charge of approving 
the conferences and perform this approval without authenticating in the 
system. 


The first step to be taken is to verify if there is any user logged in before 
liberating access to this part of the application. 


public static Result all() { 
if(user is logged in) { 
List<Conference> approved = Conferences 
. approved (true) ; 
List<Conference> nonApproved = Conferences 
.approved (false); 
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return 


ok(views html .confersnces.admin.all conferences. 
9 render (nonApproved, approved) ); 
10 } 
11 return redirect (routes.LoginController.form()); 


12 } 


How do you know if the user is logged in or not? The more experienced 
reader should have thought: just include the user in the session. And this is 
exactly the answer! 


Session is a way to keep the data referring to a given user through the 
various requests of this same user. In general, an entry is created in a 
cookie in the client's browser with an id for that user. A structure is created in 
the server that associates this id with some information specifically from this 
user. 


When the user logs in, we have to add his relevant information to the 
session. Therefore, we can verify our if. 











1 public static Result login() { 

2 //cest of the code 

3 

4 if (possibleUser.isDefined()){ 

5 
session ().put ("email",possibleUser.get().getEmail()); 
6 return 

7 redirect (controllers.admin 

8 .routes.AdminConferencesController.all()); 
9 } 

10 

11 DynamicForm errorForm = 
form.fill(requestForm.data()); 

12 errorForm.reject ("Login/password invalid"); 


13 return 

forbidden (views. html.login.render (errorForm) ); 
14 

15 } 





Through the method session we have access to the object of the type 
Session, which allows us to add information in the user’s session. 


Now, we can use this same session with the code that presents the events 
that are still pending for approval. 


1 public static Result all() { 

2 if(session().containsKey("email")) { 

7 List<Conference> approved = 

Conferences .approved (true) ; 

4 List<Conference> nonApproved = 
Conferences.approved (false) ; 

5 return 

ok (views .html.conferences,admin.all conferences. 
render (nonApproved, approved) ); 


3 


} 


return redirect (routes.LoginController.form()); 


} 
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More about the sessions of Play 


The more experienced programmer might be wondering why the complete 
object of the type User was not left in the session. The reason is a restriction 
imposed by the framework itself. 


A web session is the way that was found by developers to maintain the 
client state on the server side. The main problem is that, if the application 
needs to be run on multiple servers (scaling out), this state kept on a server 
becomes the bottleneck for scalability. The application will have to find a 
way to share the data held on a machine with other servers that are part of 
load balancing. 


As the Play proposal is to be as stateless as possible, it only allows strings 
to be added in the session. All the information already added is written in the 
client cookie and passed in every request. 


v Request Headers view source 
Accept: text/html, application/xhtml+xm1, application/xm1; q=@.9, image/webp, */*; q=0.8 
Accept-Encoding: gzip,deflate, sdch 
Accept-Language: en-US, en; q=0.8, pt-BR; q=0.6,pt;q=0.4,de;q=0.2 
Cache-Control: max-age=0 
Connection: keep-alive 
Cookie: treeForm_tree-hi=treeForm: tree: applications; PLAY_LANG=pt-BR; JSESSIONID=b8ab0743aad8e472ae 
7alee565f@; request_method=GET; _youpet—web_session=T@1xcWpiQXNnb1FzQWpnM LpWeTN3UEJvY LLUS LRUT21LZ3ZS 
UzRHSG85Z2c4MmVmRzZSNFBuY jNVTZBJ bnpXNkZLR2R3VFBESWt iW LY OMVNyZm9@YO@tQVOtLSW82ZkoyTDZNemhtZDVBQ2MwMmV3 
cmZoZFp3cFBSVG9j bj Jj ZFgicFIxYkJ3WGptMHYxWHVnNmNBeC9WM2 LpWVg5MX LaWGNJUmc3M INS TWdFeC84VEFPUjRTTHNDdj LL 
bTBXNW1SUFVj TXVSO0TJaRDVARkxJenNEaVVLNUEWMExXdkpkQVdFMFQrVW1SRzR LaWwNUMWwzTzhS5aGMyeStCa@tUWLhHRFc1Ymgy 
SFVCL3ExT LpYcj FsSSt3Smc9PS@tQ LhsNLRrSFIvTXBRSZFOUmpxTURpdz@9—1f14c873174376b20b48d55ece4cb4fcfb3227 
96; cidade=; PLAY_FLASH=; id=fdeafd2595f3588911407 f30fb84191c9138f3da2112cd152584f864a38059c8ee71ed5 
4f3d2797675864ed3fd8121f caa6a735d81da8b8 fc215082c057b187ab25e52 f946de903be f99F108bdf8757c67bcb79652F 
999a0374035ef092d7c6e665259f2c66e5e8d9995688466 fad@573c0@5ee638d30d1df7d549d822b19e654; PLAY_SESSION= 
"38bdd297c75158877806c885ca97ac04aa975dfb—email=test%40gmail. com" 


Fig. 11.2 


Note that the key email is part of the value of the entry PLAY_SESSION. 
Therefore, your application can scale to as many servers as you want. As 
the data are passed in every request, it does not matter in which server the 
request falls. 


If you still want to maintain the state on the server, it is recommended to use 
the cache API presented in the previous chapter. Its default implementation 
is based on the EhCache library, and it already has the implementation for 
running in distributed mode. Another implementation that can be chosen is 
the Infinispan, a Red Hat project that is used as cache on the WildFly 
application server. 


Just be careful with one thing: on the cache API, the programmer himself is 
responsible for taking care of the associations of keys. For example: 


1 Cache.set("user",userObject) ; 


This code will result in just one user in the cache; after all, the cache in Play 
is global. Remember to always associate an identifier with the key in order 
to differentiate one user from another. Generally the database ID is enough. 


11.3 Composing actions to avoid code duplication 


The approach to check if there is an email in the session actually solves our 
problem. The detail is that we need to do this check for controlling the 


cache, list of approved conferences, conferences approval, etc. In the 
current way, we will have to spread that if everywhere. 


For this type of situation in which a code should always be performed before 
an action, Play provides the mechanism Action Composition. 


1 public class AuthenticatedAction extends 
Action.Simple{ 
2 @Override 
public Promise<SimpleResult> call (Context ctx) 
throws Throwable { 
//code before 


delegate.call (ctx); 


// code after 
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} 


By inheriting from the inner class Action.Simple, you override the call 
method and are able to execute code before a specific action. The variable 
delegate represents the action that should actually be invoked. That way we 
can perform the control of the logged in user only in that code snippet. 


1 public class AuthenticatedAction extends 
Action.Simple{ 


@Override 
public Promise<SimpleResult> call (Context ctx) 
throws Throwable { 
String email = ctx.session().get("email"); 
if (email!=null) { 
return delegate.call (ctx); 


} 
ctx.tlash().pur ("net logged”, 
"You need to log in to access"); 
//the pure method is just a helper 
//to create and execute it in the same time. 
//No async actual code is running here. 
return F.Promise.pure (redirect ( 
routes.LoginController.form())); 
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} 


The flash method should be used when you want to add an object that 
should last until the next request. This is commonly used to add messages 
that should be displayed after a redirect. The example above is a typical 
case. 


The next step is to inform Play which actions should be intercepted by our 
controller of authenticated users. This configuration should be done through 
the annotation @With. 


1 @With (AuthenticatedAction.class) 
2 public static Result all() { 


3 List<Conference> approved = 

Conferences .approved (true) ; 

4 List<Conference> nonApproved = Conferences 

5 .approved (false); 

6 

d return 

ok (views .html.conferences.admin.all conferences. 
8 render (nonApproved, approved) ) ; 

9 } 


We can include over-specific methods or directly in the class when the 
intention is to intercept all methods. Now just configure each point of the 
application that requires authentication to access. 


11.4 Play Authentication Plugin 


As authentication is very common in applications, Play comes with a plugin 
for this case. The usage is very similar to that implemented by us in the 
previous section. Instead of using the annotation @With, lets use another 
annotation called @Security.Authenticated. 


1 
@Security.Authenticated(PlayAuthenticatedSecured.class) 
2 public class AdminConferencesController extends 


Controller { 
3 //code here 
4 } 


Just for curiosity, let’s have a look at this annotation: 


@With (AuthenticatedAction.class) 
@Target ({ElementType.TYPE, ElementType.METHOD} ) 
@Retention (RetentionPolicy.RUNTIME) 











public @interface Authenticated { 
Class<? extends Authenticator> value() 
default Authenticator.class; 
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} 


Note that it uses @With to indicate that this annotation should be read as a 
configuration for composing actions. You can also use this resource to 
create your own custom compositions. 


As we are now going to use the action already implemented by Play, we 
should just create a class that implements the way of retrieving the 
information of the session and where the user should be redirected in case 
of not being logged in. 


public class PlayAuthenticatedSecured 
extends Security.Authenticator{ 


@Override 
public String getUsername (Context ctx) { 
return ctx.session().get ("email"); 


} 


public Result onUnauthorized (Context ctx) { 
ctx.flash().put("not_logged", 
"You need to log in to access"); 
return redirect (routes.LoginController.form()); 
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9 @Override 
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} 


Note that this class is exactly the parameter passed to the annotation 
@Security.Authenticated. By the way, this is the most appropriate 
mechanism to add authentication control to your system. Enjoy what is 
ready, and focus mostly on its logic. 


11.5 Conclusion 


In this chapter, you have seen how to implement a very common 
functionality in web applications, the control of authenticated users. We also 
saw the composition of actions, which is an elegant way of not duplicating 
code throughout all the actions of our system. 


Do not stop now. The next chapter will show how the same action can serve 
different response formats. It is a short and very useful chapter! Spend 10 
minutes more and improve your knowledge. 


CAPITULO 12: 
Serving different formats 


For now, the Agendatech has only returned HTML. Nothing unusual at all 
considering that our client is a browser. But now the conferences also need to 
be displayed in a mobile application. 


As we are dealing with another application that is consuming our information, a 
data format to be exchanged between the systems should be defined. Currently, 
one of the preferred formats for applications is JSON. Play comes with a very 
good support, let’s check it out. 


1 public static Result list() { 


2 List<Conference> conferences = Conferences 
3 -approved (true); 
JsonNode json = Json.toJson (conferences); 


return ok(json); 


} 


12.1 Which format to use? 


However, now the application reached a problem because if the request is made 
by the browser, we want to return HTML, but if the request is made by the 
mobile client, the format returned should be JSON. To resolve this issue, we will 
let the client tell us which format it prefers, and our application will return the 
result or report that it does not support that format. 


Whenever an HTTP request is made, the client can pass a header called 
Accept, informing which response format it prefers. For example, when your 
browser makes the request, the Accept is like the following: 


1 text/html, application/xhtml+xml, 
2 application/xml;q=0.9,image/webp,*/*; 





Notice that the preferred form in this case is text/html. With this header at hand, 
our action can decide which response to generate. This mechanism is known as 
Content Negotiation, much used in system integrations based on REST. The 
code itself is not too complicated. 


1 @Cached(key = "home", duration = 3600) 
2 public static Result lista() { 
3 List<Conference> conferences = 


Conferences.approved (true) ; 

4 if (request () .-accepts ("text/html") ) { 

5 return ok(views.html.conferences.list 
6 .render (conferences) ); 


7 


8 if (request ().accepts ("application/json") ) { 

9 JsonNode json = Json.toJson (conferences); 
10 return ok(json); 
11 } 
12 return status (NOT ACCEPTABLE) : 


We simply check the headers and provide the return expected by the client. If 
the format is not supported, the status 406 is returned, indicating that the format 
is not accepted. 


To take the test, you can install the Google Chrome plugin called Postman, Or 
you can use a program called CURL. With CURL, we can go to the console and 
make the following calls: ‘curl --header "Accept: text/html" http://localhost:9000° 
and then ‘curl --header "Accept: application/json" http://localhost:9000°. The 
action should provide a different response for each type of call. 


12.2 Problem generated by @Cached 


If you have done the test above, you should have realized that after the first 
Request, the result is always the same, regardless of the requested format. This 
problem happens because of the use of the @Cached annotation. After the first 
request, the result is kept in the cache, and from the second request on, our 
logic is no longer executed. 


This is a limitation that cannot be overcome right now. One possible solution is 
to create two actions, one to serve JSON and another to serve HTML. Another 
suggestion is to reuse the Cache API manually. 


1 public static Result list() { 


2 List<Conference> conferences = Conferences 
3 -approved (true); 
4 MediaRange media = request ().acceptedTypes ().get (0); 





String mediaType = media.toString(); 


if (Cache.get ("home_"+mediaType) !=null) { 


(00) 


Status status = (Status) Cache 
.get ("home_"+mediaType) ; 
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10 return status; 

11 } 

13 if (request () .accepts ("text/html") ) { 

14 Status status = ok(views.html 

15 .conferences.list.render (conferences) ); 
16 Cache, set ("home text/html", status); 

17 return status; 

18 } 

19 

20 if (request ().accepts ("application/json") ) { 

21 Status status = ok(Json.toJson (conferences) ); 
22 Cache. set ("home application/json", status); 
23 return status; 

24 } 

25 return status (NOT ACCEPTABLE) ; 


26 } 


Realize that one more if was added to the code to handle the key of the cache 
according to the requested format. Remember that the @Cached annotation is 
just a customization of Play for you to use its Composite Action called 
CachedAction. If you feel that this support is very important to you, create your 
composition and use it in your application. Or even better, try to make a 
contribution to the framework! 


12.3 Conclusion 


In this short chapter we have seen how to serve different formats within our 
controllers. Furthermore, we briefly checked the problem generated by using the 
@Cached annotation. Go ahead and serve as many formats as you want. Play 
also has native support to XML, if this is what you need! 


CAPITULO 13: 
Automated Testing 


Our system comes with the main functionalities already 
implemented. We register and list the conferences that have been 
approved. We can also add more things, such as only list the 
conferences that will occur, filter by state, associate conferences to 
groups of users, etc. You are now able to implement all of these. A 
very important detail that has not been discussed until now is the 
part of testing our application. We do not want to keep running 
everything manually in order to check if things are working correctly. 


There are some test categories, usually divided between tests of 
unit, Integration, and acceptance. The first category will not be 
addressed by this book because Play has nothing new to offer in this 
area. You will continue using JUnit in the same way you may have 
read in several places. For a deeper knowledge on the theory related 
to each type of test, | recommend the book TDD in the Real World, 
by the great expert and author Maur cio Aniche. 


13.1 Integration Testing in DAOs 


In the Conferences class, there is a method that should return the 
conferences according to the approval status. Even being a simple 
rule, it already involves building a query on your database, and if you 
think about it, this is a very important rule for the application. We 
cannot display conferences that have not been approved. 


Let's begin by creating a new test case focused on testing the rules 
written in the Conferences class. This class should be created in the 
source folder called test. 


1 package integration.persistence; 


AN 





3 public class ConferencesTest { 


Q@Test 
public void shouldListOnlyApproved() { 


} 


YO Os 


} 


The method’s name already indicates what we are trying to verify. 
Now let's set our test scenario, something very common. We need to 
create some conferences, approved and unapproved, to verify that 
the method is really working correctly. 





1 public class ConferencesTest { 
2 Q@Test 
3 public void shouldListOnlyApproved() { 
4 Conference conferencel = newConference 
5 (true, "test@gmail.com") ; 
6 Conference conference2 = newConference 
7 (false, "test2@gmail.com") ; 
8 Ebean.save (Lists 
9 .newArrayList(conferencel, conference2) ); 
0 
11 } 
12 + 





With the scenario ready, we should verify if, after invoking the 
method approved , the result is what we expected. Let’s use the 
JUnit utility methods to help us. 





1 public class ConferencesTest { 

2 @Test 

3 public void shouldListOnlyApproved() { 

4 Conference conferencel = 

5 newConference (true, "test@gmail.com") ; 

6 Conference conference2 = 

7 newConference (false, "test2@gmail.com") ; 
8 Ebean.save (Lists 

9 .newArrayList(conferencel, conference2) ); 
LO 
L1 





List<Conference> approved = 


Conferences .approved (true) 


12 Assert.assertEquals(l, approved.size()); 
13 Assert.assertEquals ("test@gmail.com", 
approved.get (0) 

14 .getContactEmail ()); 

15 } 

16 } 





Notice that it is important to check whether the event returned is 
actually the approved one. If you test only the size of the list, you 
may find that your test is passing, but in fact, the unapproved event 
is being returned. This is what we call false positive. When the 
return is a list, it is usually important to do this kind of verification. 
Now we need to run our test. Let’s try to do this into the Eclipse 
itself. 


x q R vo 
Open aac oject Explorer gfu JUnit 2 2 oF IQR è= Y Oo 
Finished after 2.076 seconds 
Runs: 2/2 B Errors: 2 B Failures: 0 = 
¥ Hiintegration.persistence.ConferencesTest Runner: JUnit 4] (2.014 s) = Failure T oe 
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É] shouldListOnlyApproved (0.380 s) 
il] shouldListOnlyNonApproved (1.634 s) „ebean.Ebean SServerManager.getPrimaryServer(Ebean.java:178) 

an.Ebean $ServerManager.access$300(Ebean.java:128) 
.ebean.Ebean.find(Ebean.java:107 1) 

i ce.Conferences.approved(Conferences.java:12) 

at integration.persistence.ConferencesTest.shouldListOnlyApproved(ConferencesTest.java:32) 
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Fig. 13.1 


The exception shows that Ebean was not properly configured. The 
configuration on the properties of the database—which are already 
there in the application.conf file—is missing,. This is a problem you 
will face in any framework that attempts to help you in every part of 
the application from the controller to the persistence layer, the so- 
called Full Stack Frameworks. As this entire integration is done by 


the framework, we need it running in order to be able to perform our 
tests. 


The interesting part is that Play, just like Rails, also worried about 
this and now provides a way for you to run your test within a 
simulation of a real application! 


import static play.test.Helpers.*; 





QTest 
public void shouldListOnlyApproved() { 


1 

2 

3 public class ConferencesTest { 

4 

5 

6 running (fakeApplication(), new Runnable () 


m 





J 
8 public void run() { 
9 Conference conferencel = 
10 newConference (true, 
"test@gmail.com") ; 
11 Conference conference2 = 
12 newConference (false, 
"test2@gmail.com"); 
13 Ebean.save (Lists 
14 .newArrayList(conferencel, 
conference2)); 
15 
16 List<Conference> approved = 
t7 Conferences. approved (true) ; 
18 Assert.assertEquals (1, 
approved.size()); 
19 Assert.assertEquals ("test@gmail.com" 
20 r 
approved.get (0).getContactEmail()); 
2a } 
22 


22 bye 


Now you can take a deep breath because a lot has happened. The 
running method is the entry point for running a code like we really 
were into our application. To proceed, we need to pass as a 
parameter an instance of the class FakeApplication; it contains the 
infrastructure needed to run our code, for example, access to the 
configuration files. The last parameter, the Runnable instance, is 
just to pass the code that must be executed after the application is 
initiated. With the arrival of Java8, this code should be simpler. 
Finally, the static import was done from the methods of the Helpers 
class, which should always be used during this type of test. 


After this change, we will try to run the tests once again inside 
Eclipse. 


| Package Explorer (Ò Project Explorer gu JUnit 5% £7 PF BVA 
Workspace fter 2.126 seconds 


Runs: 2/2 E Errors: 2 B Failures: 0 E) 





v figjintegration.persistence.ConferencesTest (Runner: JUnit 4] (2.097 s) = Failure Trace cE 
E] shouldListOnlyApproved (1.964 s) J} javax.persistence.PersistenceException: Entity type class models.User is not an enhanced entity bean. 
l] shouldListOnlyNonApproved (0.133 s) = at com.avaje.ebeaninternal.server.deploy.BeanDescriptorManager.checkSubclass(BeanDescriptorMan 


= at com.avaje.ebeaninternal.server.deploy.BeanDescriptorManager.setEntityBeanClass(BeanDescriptor 
= at com.avaje.ebeaninternal.server.deploy.BeanDescriptorManager.createByteCode(BeanDescriptorMai 
= at com.avaje.ebeaninternal.server.deploy.BeanDescriptorManager.readDeployAssociations(BeanDesci 
= at com.avaje.ebeaninternal.server.deploy.BeanDescriptorManager.readEntityDeploymentAssociations 
= at com.avaje.ebeaninternal.server.deploy.BeanDescriptorManager.deploy(BeanDescriptorManager.jav 
= at com.avaje.ebeaninternal.server.core.InternalConfiguration.<init>(InternalConfiguration.java:114) 
= at com.avaje.ebeaninternal.server.core.DefaultServerFactory.createServer(DefaultServerFactory.java:2 
= at com.avaje.ebeaninternal.server.core.DefaultServerFactory.createServer(DefaultServerFactory.java:6 
= at com.avaje.ebean.EbeanServerFactory.create(EbeanServerFactory.java:58) 

= at play.db.ebean.EbeanPlugin.onStart(EbeanPlugin.java:79) 

=} at play.api.Play$ SanonfunSstart$ 1$ SanonfunSapplySmcVSsp$ L.apply(Play.scala:88) 

= at play.api.Play$ SanonfunS$start$ 1$ SanonfunSapplySmcVSsp$ L.apply(Play.scala:88) 

= at scala.collection.immutable.List.foreach(List.scala:3 18) 

= at play.api.Play$ SanonfunSstart$ 1.apply$mcV$sp(Play.scala:88) 

= art play.api.Play$ SanonfunSstart$ 1.apply(Play.scala:88) 

= at play.api.Play$ SanonfunSstart$ 1.apply(Play.scala:88) 

= at play.utils. Threads$ .withContextClassLoader(Threads.scala:18) 

=} at play.api.Play$.start(Play.scala:87) 

= at play.api.Play.start(Play.scala) 

=} at play.test.Helpers.start(Helpers.java:359) 

Æ at play.test.Helpers.running(Helpers.java:375) 

= at integration.persistence.ConferencesTest.shouldListOnlyApproved(ConferencesTest.java:34) 


Fig. 13.2 


We now receive one more exception, this one a little stranger. Let's 
have a look at it. 


jJavax.persistence.PersistenceException: 
Entity type class models.User is not 

an enhanced entity bean. Subclassing is not 
longer supported in Ebean 


NO fF 


A CW 


Let's not waste much time on it. This exception means that the 
bytecode of our class should be changed so that Ebean can work. Its 
purpose is that it can have control over the objects loaded (for 
example, not load twice the object with the same id). Formerly, this 
was done by creating a child class at runtime. Now this is done 
through instrumentation at the time of loading classes. 


The best way to solve this problem is to run the tests via the Play 
console! It already has a command called test that runs our tests 
and already instruments our classes. To begin testing, you can open 
the console and type test. 














| root@celerate-caelum: ~ mysql bash I bash 








[agendatech-en] $ test 

[info] Compiling 1 Java source to /Users/albertoluizsouza/ambiente/desenvolvimento/scala/agendatech-en/target/scala-2.10/test-c 
lasses... 

[info] integration.persistence.ConferencesTest 

[info] + shouldListOnlyApproved 

[info] 

[info] 

[info] Total for test integration.persistence.ConferencesTest 
[info] Finished in 0.002 seconds 

[info] 1 tests, @ failures, ® errors 

[info] Passed: Total 1, Failed @, Errors ®, Passed 

[success] Total time: 5 s, completed Jul 7, 2014 ci 15:36 PM 
[agendatech-en] $ 


Fig. 13.3 


This type of testing, which requires us to speak directly to part of the 
infrastructure of our application, is called Integration Testing. It 
makes a lot of sense for parts of the system that cannot be 
simulated. For example, working with a fake database can give the 
false impression that our application is working correctly. 


Changing the settings of testing environment 


Right now we are running our tests with the database used in the 
development. With this, we leave in the database data from tests 
that we used during the development, which can cause some 
confusion. 


In this case, not to mix the objectives, it would be better to run the 
tests in another database, specifically for testing. When we create 
the object of the type FakeApplication we can pass it a Map with the 
settings we want to use. 


HashMap<String, String> confs = 
new HashMap<String, String>(); 
confs.put ("db.default.url", 
"jdbc :mysql://localhost/agendatech play test"); 
running (fakeApplication(confs), new Runnable() { 
//code here 


} 


SWS) OW WNhHO-e 


That way we can override any settings that may exist in the 
application.conf file. 


Another way, that this author finds most appropriate, is to use a 
different file for the test configuration. The idea is to create a file 
named test.conf in the settings folder and load it during the tests. To 
do this, just change the file “build.sbt’. 


1 //rest of the file 


J 
2 


3 javaOptions in Test += "- 
Dconfig.file=conf/test.conf" 


Now, whenever the tests are run by the Play console, the test file will 
be used. That way you have a place, already default in the 
framework, where you can see the settings for testing. 


13.2 The problem of clearing the database 
between tests 


Now let's add another test for our logic of listing the conferences. We 
want to know if it can list the events that have not yet been 
approved. 


L Jf « 
3 @Test 
4 public void shouldListOnlyNonApproved() { 
5 running (fakeApplication(), new Runnable() { 
6 @Override 
7 public void run() { 
8 //just to encapsulate the setup 
9 initData(); 
10 List<Conference> nonApproved = 
Conferences 
rI .approved (false); 
12 Assert.assertEquals (1, 
nonApproved.size()); 
13 Assert.assertEquals ("test2@gmail.com", 
nonApproved 
14 .get (0) .getContactEmail ()); 
15 } 
16 j)? 
17 
18 } 





After running the tests with the test command, we notice that the 
second test failed. 


[error] Test integration.persistence. 





1 
ConferencesTest.shouldListOnlyNonApproved 
3 failed: expected:<1> but was:<2> 





The message is clear: the first assert indicates that we just wait for 
an approved event, but two events were returned. The reason for 
this is that Play does not clear the tables of the database during the 
tests. In our case, as the two tests insert data via the initData 
method, one test ends by influencing the other. A solution suggested 
by the documentation is to use a database in memory, but this can 
lead to complications due to any specific query in your database. 


Another solution that can be used is to clean up data between the 
tests. 


1 public void dropDb() { 
3 String serverName = "default"; 
4 


EbeanServer server = 
Fboean.getServer (serverName) ; 








7 ServerConfig config = new ServerConfig(); 


8 
9 DdlGenerator ddl = new DdlGenerator(); 
10 ddl.setup((SpiEbeanServer) server, new 
MySqLPlattorm(), 

11 config); 


3 // Drop 
14 ddl.runScript (false, ddl.generateDropDdl ()) ; 


16 SqlUpdate dropEvolutions = 
Lt Fbean.createsSqlUpdate ("drop table 








Ebean’s runScript method is responsible for dropping the existing 
tables. The problem is that if we stop there, the table 


play_evolutions, which controls the execution of the migrations, 
becomes populated as if Play has already run the evolutions. To 
work around this situation, it is also necessary to drop this table. 
Therefore, the framework will always create everything for us. Ina 
very large system, this approach can become a little slow, and then it 
might be worth it to enter with a database in memory, for example 
the H2. 


Now just make sure this method is invoked after each test being run. 


1 @Test 
public void shouldListOnlyApproved() { 
running (fakeApplication(), new Runnable() { 
public void run() { 
initData(); 
List<Conference> approved = Conferences 


-approved (true) ; 
Assert.assertEquals(l, 
proved.size()); 
Assert.assertEquals ("test@gmail.com", 
approved.get (0) .getContactEmail()); 


` @ 
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dropDb (); 
} 


P)? 
} 





@Test 
public void shouldListOnlyNonApproved() { 
running (fakeApplication(), new Runnable() { 
@Override 
public void run() { 
initData(); 


MONNNNNNFF EF FEF I 


27 List<Conference> nonApproved = 
Conferences 


28 .approved (false); 
29 Assert.assertEquals(l, 
nonApproved.size()); 
30 Assert.assertEquals ("test2@gmail.com", 
nonApproved 
31 .get (0) .getContactEmail()); 
32 
33 dropDb (); 
34 } 
5 j)? 
36 
37 } 


Normally, initData and dropDb would stay in the annotated 
methods with JUnit’s @Before and @After. The problem is that we 
need to run these codes in the execution context of 
_FakeApplication_. That's why they are inside run . 


As these codes will be quite common within the tests that you are 
going to perform, these utility methods will be extracted to a base 
test class. 


public class TestHelper { 


1 

2 

3 public void dropDb() { 

4 

5 String serverName = "default"; 
6 


/ EbeanServer server = 
Fboean.getServer (serverName) ; 








8 

9 ServerConfig config = new ServerConfig(); 
10 
11 DdlGenerator ddl = new DdlGenerator(); 
1:2 ddl.setup((SpikEbeanServer) server, 








13 new MySqlPlatform(), config); 
14 

r5 // Drop 

16 ddl.runScript (false, 
ddl.generateDropDdl ()); 

17 

18 SglUpdate dropEvolutions = 

19 Ebean.createsqlUpdate 
20 ("drop table play evolutions"); 
21 Ebean.execute (dropEvolutions) ; 
22 

23 

24 } 

25 

26 fer 

27 * Should be override in order to initialize 
tables with 

28 * test data. 

29 E 

30 protected void initData() { 

31 } 

32 


33 protected void executeFakeApplication (final 
Runnable runnable) 


34 { 

35 running (fakeApplication(), new Runnable() { 
36 

37 @Override 

38 public void run() { 

39 try { 

40 initData(); 


runnable.run(); 
} 
finally { 

dropDb (); 
} 
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50 protected Conference newConference (boolean 
status, 

51 String contactEmail) { 

52 Conference conference = new Conference (); 
53 Calendar today = Calendar.getInstance(); 
54 Calendar tomorrow = Calendar.getInstance(); 
55 tomorrow.add(Calendar.DAY OF WEEK, 2); 

56 conference.setStartDate (today); 

57 conference.setEndDate (tomorrow); 

58 conference.setDescription ("description 
description"); 

59 conference.setApproved (status); 

60 conference.setName ("Scala days"); 

61 conference.setContactEmail (contactEmail); 
62 return conference; 

63 } 


And in our tests, the executeFakeApplication method should 
be invoked, with the implementation of the Runnable specific to the 
situation. 





13.3 Integration tests for controllers 


Another interesting part to be tested is if some flows of our 
controllers are being respected. For example, a user can only 
access the administration after being logged in, a conference should 
appear in the homepage after approved, etc. 


Play now provides several utility methods to make this task much 
simpler. Let's begin by checking that a user cannot access the 
administration if not logged in. 


1 package integration.controllers; 
2 
3 public class AuthenticationTest extends 
TestHelper { 
4 
private Conference newConference; 


5 
6 
7 @Override 
8 
9 





protected void initData() { 
newConference = 
LO newConference (false, 
"contact@gmail.com") ; 
11 
12 Ebean.save (newConference) ; 
13 Ebean.save (new User ("test@gmail.com", 
14 Crypt.shal ("123456"))); 
15 } 
16 
Ly Q@Test 
18 public void shouldNotAccessAdminNotLogged () 
19 executeFakeApplication (new Runnable() { 
20 
21 @Override 
22 public void run() { 
23 Result result = callAction ( 
24 controllers.admin.routes 
25 
.ref.AdminConferencesController.all(), 
26 fakeRequest()); 
27 Assert.assertEquals("/login", 
28 redirectLocation (result) ); 
29 
30 } 
31 })? 


32 } 


{ 


We are using here our base class to help on the tests. The helper 
callAction does the dirty work of invoking our action a11 as if it 
were a normal request from a user. The second argument, a fake 
request, is optional and should only be used if you want to pass 
parameters to your action. Note that the return is an object of the 
type Result, the same that you return through a regular action. 


Our test needs to verify that you have been redirected to the login 
URL, as the user is not authenticated. The RedirectLocation 
method checks that, which receives a result and returns the string of 
redirect. Remember that all of these methods came from the static 
import of the class Helpers. To verify that after login the user is 
being directed to the administration, the flow would be the same. The 
challenge is for you, dear reader. 


Another useful test is to check the flow of approval of an event. It 
would be something like the one below: 


public void shouldShowInHomeAfterApproved() { 
executaFakeApplication (new Runnable() { 


@Override 
public void run() { 


callAction ( 
controllers.admin.routes.ref. 
AdminConferencesController 
-approve (newConference.getId()), 
fakeRequest()); 
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Result result = callAction ( 
controllers.routes.ref. 
ConferencesController.list(), 
fakeRequest()); 
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0O ~l eO OB WN H 





O 
=~ 


The problem with this part of the test is that we will not be able to 
access the approval action without being logged in. A possible 
solution would be to perform the login before doing the test. 


public void shouldShowInHomeAfterApproved() { 


executaFakeApplication (new Runnable() { 
@Override 
public void run() { 


FakeRequest loginRegquest = fakeRequest () 
.withFormUrlEncodedBody ( 
ImmutableMap.of ("email", 
"testtgmail.com", “password”, 
"123456")); 


H ` L 


callAction ( 


= 
f 


ntrollers.routes.ref.LoginController.login(), 
loginRequest) ; 


= Q ` 
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callAction ( 
controllers.admin.routes.ref 
-AdminConferencesController 


pk 
f 











ii .approve (newConference.getId()), 
2 

2 fakeRequest()); 

22 

23 Result result = callAction ( 

24 
controllers.routes.ref.ConferencesController 
25 .list(), 

26 fakeRequest()); 

27 } 

28 }); 


29 } 


However, we then fall into another problem. Play will not share data 
from the first to the second request; the session created by the first 
request will not be seen by the second one. In order to solve this, it 
is necessary to pass a request as a parameter, with the data that 
would be sent via cookie and stored in the session. 














1 @Test 
2 public void shouldShowInHomeAfterApproved() { 
3 executeFakeApplication (new Runnable() { 
4 
5 @Override 
6 public void run() { 
8 FakeRequest loginRegquest = fakeRequest () 
9 .withSession ("email", "test@gmail.com") ; 
10 
11 callAction(controllers.admin.routes.ref 
12 .AdminConferencesController 
13 
.approve (newConference.getId()),loginRequest) ; 
14 
LS Result result = callAction ( 
16 controllers.routes.ref 
17 .ConferencesController.list(), 
18 fakeRequest()); 
19 String html = contentAsString(result); 
20 Assert.assertTrue (html.contains ( 
21 newConference.getName())); 
22 } 
23 })3 
24 } 


As our check is based on the email key in the session, it will work! 
Finally, the contentAsString method receives the result and returns 
the string generated by our view! With this in hand, it is easy to know 
if the approved event was displayed on the list. 


13.4 Acceptance tests 


Integration testing is generally a large slice of the test suite of your 
project, along with the unit tests. But we still have one last situation 
in which they may not be ideal. For example, we can create a test for 
the action that registers a new conference, just like the ones we 
created above; however, this is such an important part of our system 
that perhaps it is more valid to perform the test like a real user 
browsing the pages, filling in the fields and clicking the button. 


To cover these scenarios, which in general are rare but very 
important, we can use the Acceptance tests. Play comes with a thin 
integration with the library called WebDriver that allows us to create 
automated tests for browsing pages. 


1 @Test 

2 public void shouldRegisterANewConference() { 

3 running (testServer (9001, 
fakeApplication()), HTMLUNIT, 

4 new F.Callback<TestBrowser>() { 

6 @Override 

7 public void invoke (TestBrowser 
browser) 

8 throws Throwable { 

9 browser.goTo 


> 


U 


'http://localhost:9001/conferences/new"); 


( 








11 browser.fill 

("input [name='name']") .with("Scala Days"); 
1:3 browser.fill 

14 


("input [name='contactEmail']").with ( 
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"playinpractice@gmail.com") ; 
16 } 

17 

18 Ws 

19 } 





Note that, unlike the other tests, we were forced to mount a real 
server in a port. The parameter HTMLUnit indicates that we use a 
browser with no graphical interface, but we could have passed, for 
example, FIREFOX, and then an instance of Firefox would be 
opened to run our tests. 


The last parameter is a callback, just like the instance of Runnable 
passed for integration testing. As it was necessary to receive a 
parameter that precisely represents the browser being used, Play 
had to create a new interface. The class TestBrowser has very 
intuitive methods, and the code is almost self-explanatory. First we 
browse to an address, and then we are able to complete the 
necessary inputs. 


Let's take a look at the entire test code now using our base test 
Class. 


1 package acceptance; 


9 


a 


3 public class RegisterConferenceTest extends 


TestHelper{ 
4 
5 Q@Test 
public void shouldRegisterANewConference() { 
F.Callback<TestBrowser> userFlow = 
new F.Callback<TestBrowser>() { 
@Override 


public void invoke (TestBrowser browser) 
throws Throwable { 
browser.goTo 
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("http://localhost:9001/conferences/new") ; 





15 browser.fill 

16 ("input [name='name']") .with("Scala 
Days") 

17 browser. fill 

18 ("input [name='contactEmail']™") .with ( 
19 "playinpractice@gmail.com") ; 

20 browser. fill 

21 

("textarea [name='description']"™") .with ( 

22 "Everything about the scala 
world”); 

23 browser. fill 

24 


("select (nane="stare* |”) .wlen ("Sao PAULO"); 
25 


browser.fill ("input [name='site']") .with ( 

26 "http://www.scaladays.org/") ; 
27 browser.fill 

28 

("input [name='twitter']").with("@scaladays"); 
29 browser.fill 

30 


("input [name='startDate']").with("2016-12-13"); 
31 browser.fill 


32 ("input [name='endDate']") .with("2016- 
12-16"); 

33 browser.submit ("input [type='submit']"); 
34 Assert.assertEquals ( 

35 "Conference registered!", 

36 

browser.$ (".success msg") .getText()); 

37 } 

38 J; 

39 executeAcceptance (userFlow); 

40 } 





41 } 


Note that it is already a much larger testing code due to the 
manipulation of form fields. The important part is that if there is an 
update in this view and, for example, the name of an input is 
changed, our test will break and we will have a quick feedback. 


Since the acceptance tests are more time consuming, they should 
be created after enough consideration. Verify which pages are 
important to the system and cannot break! 


13.5 Conclusion 


The tests are one of the most important parts of the application. 
Through them we have a quick feedback about any changes in the 
code, and we can react quickly to any problem. The helpers offered 
by Play make the tasks of the developer much easier, allowing their 
writing to be done in a clear and objective way. 


CAPITULO 14: 
Layout and reusing views 


One point overlooked by our application, so far at least, is its 
appearance. While it is not the kind of thing most appreciated by 
developers, it is necessary to pay attention to the construction of 
HTML, respecting the design created. 


To make our lives easier, we import everything related to that part 
from the Agendatech that is already running. As we are rebuilding 
the application using another technology, it makes sense to reuse all 
the CSS, Javascript, and HTML already created in the current site. 


14.1 Organizing static resources 


The astute reader may have noticed that in the file routes, there is a 
route associated with one controller named Assets. 


1 GET /assets/*file 
controllers.Assets.at(path="/public", file) 


As we did not create this class, the only option left is that it was 
delivered ready by Play. This class is responsible for loading any 
static files requested by the client. Note that any URL begun with 
assets will be handled by the action at of this controller. Now, the 
first thing we will do is to alter our listing page to respect the layout of 
the original Agendatech, importing the CSSs. 


1 <head> 
2 <title>Agendatech - Tech conferences</title> 
3 <link rel="stylesheet" media="screen" 


A 
L 
‘It 


href="@routes.Assets.at ("stylesheets|/|stylel.|ess[") "/ 
> 
<link rel="stylesheet" media="screen" 


Oy O1 


href="@routes.Assets.at ("stylesheets|/|fornl.|css|") "|/> 
7 <link rel="stylesheet" media="screen" 


O 
O 
C 


href="@routes.Assets.at ("stylesheets|/contatof.|ess|") 
"y> 

9 <link rel="stylesheet" media="screen" 
10 
href="@routes.Assets.at ("stylesheets|/}j query- 
uil.jess|") "> 


11 </head> 


It is nothing we have not seen before. We use the reverse route to 
reference the action and pass the required parameters. A default 
value for the parameter path is set in the routes file; by the way, this 
is a feature of the Scala language. This default value means that all 
these static resources, also known as Assets, are in the public 
folder. The second argument indicates the location and then we have 
to pass the remainder of the path. The Play convention states the 
following: 


e public/javascripts for javascript files 
e public/stylesheets for css files 
e public/images for application images 


The class controllers.Assets is capable of doing much more than 
just finding the asset and serving it to us. This same class can 
control resources such as: 


e Cache 
e Gzip 


That's why it is highly recommended that you always use it. 


14.2 Creating the system template 


Let's now implement the entire layout part. First, let us ascertain the 
look that we want. 


Eventos de tecnologia no Brasil 











1 3 Mais informações ] Divulgue 
Destaque 
13 ' 
Abril 
1 3 Mais informaçi ões 
Abril 
Fig. 14.1 


All of this is the work of HTML + CSS, which is by far not the most 
important part of this book here. We will focus on how to take 
advantage of the views of Play for building these pages. 


An important detail to keep in mind is that in every Agendatech page, 
the top, Footer, and side banner parts will be the same. 


Like with Java code, we will apply the principle of DRY (Don’t Repeat 
Yourself) in our views. Let's isolate the part that gets repeated in a 
single view file, for example, ‘main.scala.html’: 





1 <html> 
2 
3 <!-- HEAD INFO -=--> 
4 <!-- 
a ee ae a ee ae ee ee a 
5 <head> 


6 <title>Agendatech - Tech 


conferences</title> 





7 <link rel="stylesheet" media="screen" 
8 
href="@routes.Assets.at ("stylesheets|/|style|.|css|") "| 
9 /> 
10 <link rel="stylesheet" media="screen" 
11 
href="@routes.Assets.at ("stylesheets|/lforn|.|cs s) "|> 
T2 <link rel="stylesheet" media="screen" 
13 href= 
14 
"@routes.Assets.at ("stylesheets|/|contato.|cs sl") "|> 
15 <link rel="stylesheet" media="screen" 
16 href= 
17 
"@routes.Assets.at ("stylesheets|/|j query-uil.|ess[") "> 
18 <link 
href='http://fonts.googleapis.com/css? 
19 family=Source+Sans+Pro:400,900' 
20 rel='stylesheet' type='text/css'/> 
21 <link 
href='http://fonts.googleapis.com/css? 
22 family=Lato:100,400' 
23 rel='stylesheet' type='text/css'/> 
24 </head> 
25 
26 <l== BODY ==> 
27 <l-- === MMMM 
==> 
28 <body> 
29 
30 <div class="boxed"> 
31 
32 <!-- HEADER --> 
33 <l- S555 mr $5 55 S55 5555555 
--> 


34 <div id="header"> 


35 @header () 





36 </div> 

37 

38 <!-- MAIN --> 

39 <l-- SSSsSSSSSSS SSS SSS SSS SSS SS SS SSS 5555555 
--> 

40 <div id="content"> 

41 

42 <div style="clear: both"></div> 

43 <div class="container"> 

44 

45 xl== MENU ==> 

46 <!-- 

SS = SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS ES SS SS 
47 @menu () 

48 

49 <div class="left-container"> 

50 <!-- WHAT CONTENT GOES HERE? --> 
51 </div> 

52 

53 </div> 

54 

JS <!-- RIGHT CONTENT ==> 

56 Qright_ content () 

57 

58 <div style="clear: both"></div> 

59 

60 </div> 

61 

62 </div> 

63 


64 <div style="clear: both"></div> 
65 

66 <div id="footer"> 

67 

68 <div class="container"> 

69 <a href="/"> 


70 <p 
class="logo footer">Agenda<span>tech</span></p> 


71 </a> 
T2 

T3 <p> 
74 <a 


href="@routes.ConferencesController.list"> 
715 Home 


76 </a> | 

Ty <p class="copy"> 

78 Copyright 2010. All Rights Reserved. 
79 </p> 

80 </div> 

81 </div> 

82 

83 <script src="@routes 

84 .Assets.at ("javascripts|/}j query- 
Ilala. min]. 55 sl") "></script> 

85 </div> 

86 </body> 

87 </html> 


The file is long, but there is almost nothing you have not seen 
before. In case you have any question at this time, do not hurry; it 


will be answered in a few minutes. An interesting detail is the review 
with capital letters in the middle of the file indicating the place where 
the specific content of a page should go. The idea is that the specific 


pages, for example, a listing of conferences, would be able to pass 
only that portion of the HTML for our view, which is the template of 
the system pages. 


And that is precisely what we are going to do! In case you forgot, our 


views are compiled to classes with the render method, which can 


receive parameters. Basically what we want is to pass the HTML that 


should be put right there in that space. With this in mind, our view 
would be as follows: 


@ (content: Html) 


1 

2 

3J dei 

4 <div class="left-container"> 
5 @content 
6 </div> 

| 

B aas 

9 </html> 

In the view of the listing of events, we can just invoke the render 
method of main by passing the content that should be placed there. 











1 @(conferences:List[Conference]) 
2 
3 @main { 
4 Qif(flash.get ("success msg") !=null){ 
5 <span class="success msg"> 
6 @flash.get ("success msg") 
7 </span> 
8 } 
9 <ul> 
10 @for (conference <- conferences})| k 
11 kladiv class="evento clearfix" 
1 id="evento Ccontersnce.getid() "> 
L3 <div class="data"> 
14 Qif (conference.isHappening()){ 
15 <p>@Calendar.getInstance () 
16 .get (Calendar.DAY OF MONTH) </p> 
17 }else { 
18 <p>@conference.getStartDate () 
19 .get (Calendar.DAY OF MONTH) </p> 
20 } 
2I <small>@conference.getStartDate(). 





22 
getDisplayName (Calendar.MONTH, 
23 Calendar.LONG, 


24 new Locale ("en","US")) 








25 </small> 

26 </div><!-- fim class="data" --> 

27 

28 Qif (conference.hasFeatureImage()){ 
29 <div class="logo img clearfix"> 
30 <img 
src="@conference.getFeatureImageSrc()"/> 

31 </div> 

32 jelse{ 

33 <div class="logo clearfix"> </div> 
34 } 

35 

36 <div class="info"> 

37 <p id="evento"> 

38 <a href="">More information</a> 
</p> 

39 <small></small><br/> 

40 

41 <p class="tags"> 

42 </p> 

43 <br/> 

44 </div> 

45 

46 </div> 

47 

48 } 

49 </ul> 

50 

5i 3} 


Notice that it was not necessary to invoke the method render. This 
happened because the generated class also has a method called 
apply that, in Scala, can be invoked without the need of a name. 
The actions of `@main.apply {...}| and ‘@main{}’ @ are exactly the 
same. 


14.3 Improving readability with includes 


We have a somewhat extensive code inside the loop that builds the 
conferences to our listings. Moreover, this piece of HTML should 
also serve to build the conference detail page, search for 
conferences, etc. 


Let's take this snippet and isolate it in another view, in order not to 
keep repeating this code. 


1 @(conference:Conference) 
2 <div class="evento clearfix" 

















3 id="evyvento Gconterence.getid() "> 

4 

5 <div class="data"> 

6 @if (conference.isHappening()) { 

7 <p>@Calendar.getInstance () 

8 .get (Calendar.DAY OF MONTH) </p> 

9 telse { 
10 <p>@conference.getStartDate () 

11 .get (Calendar.DAY OF MONTH) </p> 
T2 } 

13 <small>@conference.getStartDate(). 
14 getDisplayName (Calendar.MONTH, 
15 Calendar.LONG, new Locale ("en","US") ) 
16 </small> 

17 </div><!-- fim class="data" --> 

18 

19 Qif(conference.hasFeatureImage ()){ 
20 <div class="logo img clearfix"> 
21 <img 
src="@conference.getFeatureImageSrc()"/> 
22 </div> 
23 }else{ 


24 <div class="logo clearfix"> </div> 


29 } 


26 

27 <div class="info"> 

28 <p id="evento"><a href="">More 
information</a></p> 

29 <small></small><br/> 
30 

31 <p class="tags"> 

32 </p> 

33 <br/> 

34 </div> 

35 

36 </div> 


Again, we are working with the fact that the view generates a class 
with a method that can take parameters. We defined that we need a 
conference as an argument, and now any page of our application 
can invoke this view in order to generate this snippet of code. Let's 
see the listing now. 


1 @(conferences:List[Conference]) 





2 

3 @main { 

4 Cit itlash.ger ("success msg") != null){ 
3 <span class="success msg"> 

6 @flash.get ("success msq”) 

7 </span> 

8 } 

9 
10 <ul> 

rr @for (conference <- conferences))| k] 
12 list _detaill(lconference)| 
13 } 
14 ~\/fal> 
15 

16 } 


It’s much easier to read! This resource of isolating a snippet of HTML 
and reusing it is called include in web development. And with the 
powerful views of Play, it is very easy to use. Use and abuse it to get 
your pages as readable as possible. You may have noticed that 
several includes were used in the main template of the system for 
organizing the menu, header, etc. 


14.4 A little more Scala for views 


One last interesting point of our event listing is to display the month 
and day of the event that will occur. Just to become more clear, let's 
have a look at the desired layout. 


2 6 More information 


Junho 
Fig. 14.2 
It should display only the number of the day and the name of the 


month of the event. An example of code for this would be the 
following: 


+ 


Calendar date = Calendar.getInstance(); 
date.get (Calendar.DAY OF MONTH) ; 
date.getDisplayName (Calendar.MONTH, 
Calendar.LONG, 
new Locale("en","US")); 


NO 


O A W 


The problem with this kind of logic in the page is that it can quickly 
become a bit more complicated. For example, if we have to verify the 


preference of language sent by the browser, we then have to write 
the name of the month according to the result. It is better to let these 
logics of the view become isolated in some other class. 


The natural way would be to write a utility class like the one as 
follows. 


1 public class DateFormatter { 


2 public static int dayAsNumber (Calendar 
calendar) { 

3 return 
calendar.get (Calendar.DAY OF MONTH) ; 

4 } 

5 

6 public static int monthAsString (Calendar 
calendar) { 

7 return calendar. 

8 getDisplayName (Calendar .MONTH, 

9 Calendar.LONG, 

10 new Locale("en","US")); 

11 } 

12 } 





And then, in the list, this class could be used. 


1 @if (conference.isHappening() ) { 

2 
<p>@DateFormatter.dayAsNumber (Calendar.getInstance 
() ) </p> 

3 }else { 

4 <p> 





()) 





@DateFormatter.monthAsString (conference. getStartDa 
te()) 
10 </small> 


Much better. People from the world of standard development in Java, 
using JSP as view, do this kind of work with the taglibs of the JSTL 
package. 


Going beyond now, using some Scala code, we can make the above 
code even simpler. Imagine that! Instead of continuing to use this 
class every time, we could simulate that the Calendar itself has 
these methods. Something like this: 


<p>@conference.getStartDate() .dayAsNumber</p> 





} 


1 €import. infra.DateFormatter. 

2 

3 @if (conference.isHappening()) { 

4 <p>@Calendar.getInstance().dayAsNumber</p> 
5 }else { 

6 

T 

8 





<small>@conference.getStartDate() .monthAsString</s 
mall> 


Very well, we can do this through a small Scala snippet. 


1 object DateFormatter { 

2 

3 implicit def 
calendar2PimpedCalendar(calendar: Calendar) = 

4 new { 


5 def dayAsNumber = 
calendar.get (Calendar ,;DAY OF MONTH) 

6 

7 def monthAsString = calendar. 

8 getDisplayName (Calendar.MONTH, 

9 Calendar.LONG, 


10 new Locale("en", "US")) 


} 


The method marked with the keyword implicit causes the Scala 
compiler to identify any call to the methods dayAsNumber and 
monthAsString in an object of the type Calendar and then return 
the new object that has these two methods. Therefore, we can 
simulate the addition of new methods to existing classes. The 
compiler does not have to get it all the time; we should import the 
class in the places where we want such functionality. That’s the 
reason for the line with the import in our view. 


If you want this helper in many parts of the code, you will have to 
keep adding the line of import. To improve it even more, we can 
configure Play to add some automatic imports in our views. Only the 
‘puild.sbt° file should be changed. 


| //rest of the code 
3 templates Import. += "infra.DateFormatter. " 


This is an important resource because this way you do not need, for 
example, to keep all your models in the models package. Just 
create the structure you want and add the imports here. 


14.5 Conclusion 


In this chapter, we have seen the power of the views mechanism 
offered by Play. By treating them as a single class, it is very easy to 
perform compositions and repackage them during the development 
of your system. It is very important for the maintainability of your 
application to maintain the organization of views. 


CAPITULO 15: 
Internationalizing the application 


So far, all the application texts are written directly on the pages. For 
example, let's analyze the view ‘menu.scala.html’. 


1 <li class=""><a href=""class=""> 
2 <i class="">About</i></a> 

3 </li> 

4 <li class=""><a href="" class=""> 
5 <i class="">Ical</i></a> 

6 </li> 

7 <li class=""><a href="" class=""> 
8 <i class="">RSS</i></a> 

9 </li> 
10 <li class=""><a href="" class=""> 
11 <i class="">Contact</i></a> 
12 </li> 





If we wanted to have a version of Agendatech in Portuguese or any 
other language, a new page should be created. Clearly, this model is 
not ideal; the duplication of the entire page just because of a 
different language makes the system maintenance almost 
impossible. By the way, this technique that allows people of different 
nationalities access your application is known as 
Internationalization. 


15.1 Externalizing strings 


As expected, once again Play comes with native support for 
internationalization. In fact, we have already used it a little when we 
set up the validation messages. If you do not remember, we left 
those messages in a file named messages. 


1 constraint.required = Please fill this field 

2 error.required = This field is required 

3 error.FromNow = Date must be greater or equals 
today 

4 constraint.frowNow = This field was not filled 
correctly 


This will be exactly the file where our strings will be externalized. 
Let's use the menu as an example. 


1 about = About 


2 ical = Ical 
3 rss = RSS 
4 contact = Contact 


Now that the strings have been set up, we can recover this 
information directly from the page. 


1 <li class=""><a href="" class=""> 

2 <i class="">@Messages ("about")</i></a> 
3 </li> 

4 <li class=""><a href="" class=""> 

5 <i class="">@Messages ("ical")</i></a> 
6 </li> 

7 <li class=""><a href="" class=""> 

8 <i class="">@Messages ("rss")</i></a> 

9 </li> 
10 <li class=""><a href="""class=""> 
11 <i class="">@Messages ("contact") </i></a> 
12 </li> 





Very simple! The Messages Class is written in Scala, but note that it 
does not cause any negative impact to the programmer who is 
writing the view. Think of that as a different syntax, just like the 
Expression Language in JSP. An interesting detail is that if the key 
passed is not found, Play will use the key itself as text to be 
displayed. 


The next step is to allow users who speak Portuguese to understand 
the texts of our application. And that's the difference: instead of 
changing the page, you need only to create a new file. Following the 
convention of Play, the filename should be messages-user location. 
For example, for users who speak the Portuguese language in 
Brazil, the filename will be messages.pt-BR. Below is an example: 


1 about = Sobre 
ical = Ical 

3 rss = RSS 

4 contact = Contato 


NO 


A question that may be in your head is how Play will know which 
language to use. Always remember that the most common way for a 
client, in this case the browser, to pass information related to the 
desired settings on the server is by using the headers of the HTTP 
protocol, just like what was done to negotiate the format of response 
in the chapter "Serving different formats". Right now, when you make 
a request from your browser to the application, it passes a header 
indicating in which language it prefers the response. 


Accept-Language: ‘en-US, en; q=0.8, pt-BR; q=0.6, pt;q=0.4,de;q=0.2 
Fig. 15.1 


As you can see, the name of the header is Accept-Language. 
Notice that several language options are passed; it will all depend on 
how your browser is configured. For example, to change this setting 
in Firefox, just access the Preferences menu and then select the 
*Content* tab. 
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Fig. 15.2 





You can even add more languages if your application really has to 
support multiple languages. When the language preference is 
changed, the requests are now automatically made with a new value 
in the Accept-Language. Play will analyze the favorite languages 
and try to find the first that can be attended by your application. 


A point of which you should be aware is the number of externalized 
strings. If it is too high, you will need a strategy for the organization. 
The most common way is to create a hierarchy, separating the 
strings into categories. An example could be: 


menu.about = About 
menu.ical = Ical 
menu.rss = RSS 
menu.contact = Contact 


me WN EF 


This way, it facilitates the search for specific strings inside the file. 
The hierarchy level will depend on the complexity of your pages. 


At this very moment, we have two message files, the messages and 
the messages.pt-BR, and you would be asking where is the file 


specifically for the English from the United States. Note that before, 
even with no English language file, the validation messages were 
being respected. That’s exactly what the messages file is for. Play 
uses it whenever the language indicated by the browser is not found 
in any other file. This file is called fallback. 


One last detail, but it’s very important. You need to configure Play to 
accept the languages that you need. In order to do that, we only 
need to change the application.conf. 


1 application. Langs="en-US, en, ot-BR” 


You specify, respecting the order of importance, which languages 
your application needs to handle. 


Adding parameters to the messages 


Another very common situation when displaying internationalized 
messages is that the message should be dynamically built. For 
example, in the administration page, we want to welcome the user 
who just logged into the system. 


ji 
@ (nonApproved:List[Conference],approved:List[Confe 
rence | ) 


2 <html> 

3 <body> 

4 <div> 

5 @Messages ("admin.welcome") 
</div> 


rest of the file 
And the message in the file would be something like this: 


1 admin.welcome = Welcome 


Play uses the standard Java classes under the hood for loading 
message files, also called bundles. To specify that the message 
expects a parameter, its index should be specified in the message. 


1 admin.welcome = Welcome {0} 


Now we only need to pass the necessary parameter to the message. 


@Messages ("admin.welcome",session().get("email") ) 


It is important to remember that if the parameter is not passed, Play 
will display {0}. The information used here is at the session of Play, 
but remember that only objects of the type String can be stored 
there. If you need a complete User object, you can use the Cache 
API, which has already been seen in the book. The only caution is 
that you have to deal with the keys of the Cache in order to 
differentiate the users logged in to your application. Use email as 
key, and everything will be fine. 


15.2 Changing the language programmatically 


Respect for the language suggested by the browser is a great way to 
try to set the preferred user language. The problem with this 
approach arises if the configured language is not actually the 
preferred one. At this moment, if you are thinking that everyone can 
change this easily, think of all those people you have ever met who 
did not have much knowledge of computing. My mother for example, 
despite using a browser on a daily basis, would not know how to 
make this configuration. 


A strategy adopted by some sites is to provide links so the user 
himself can set the preferred language. 


Latin America 


E Argentina/ Spanish E Ecuador / English Wa Jamaica / English B= Puerto Rico / English 

HE Bolivia / English E Ecuador / Spanish BEA Jamaica / Spanish B= Puerto Rico / Spanish 

EE Bolivia/ Spanish SE! Salvador / English == Nicaragua/ English S= Republica Dominica / English 
ES Brazil / Portuguese == ElSalvador / Spanish = Nicaragua / Spanish S= Republica Dominica / Spanish 
ML. Chile / Spanish ə» Guatemala / English Je] Peru / Spanish Trinidad & Tobago / English 
Wā Colombia / Spanish ») Guatemala / Spanish m™ Panama/ English EN Trinidad & Tobago / Spanish 
f= Costa Rica/ English SS Honduras / English m™ Panama/ Spanish W Venezuela / Spanish 

= Costa Rica/ Spanish SS Honduras / Spanish 


Fig. 15.3 


Let us adopt the same approach with Agendatech. Initially, we are 
going to add the links so that the user can choose. We will do this in 
the file menu.scala.html. 


1 <li class=""> 

2 <a href="Qroutes.CookieLang.mudaIdioma? 
lang=pt-BR"> 

3 <i class="">@Messages ("idioma.pt br")</i></a> 
4 </li> 

5 <li class=""><a 
href="Qroutes.CookieLang.mudaIdioma? lang=en-US"> 
6 <i class="">@Messages ("idioma.en us")</i></a> 
7 </li> 


Notice that the controller that will handle this logic does not exist yet. 
Your console should even be displaying a compilation error informing 
you that this route does not exist. 


In order to calm your anxiety, we will soon implement a controller 
that performs the change of language. 


public class CookieLang extends Controller { 


1 
2 
3 public static Result changeLang() { 
4 String lang = 

request ().getQueryString ("lang"); 

= 


Y 


response ().setCookie (Play.langCookieName(),lang) ; 


6 return 
redirect (routes.EventosController.lista()); 
gy 


9 } 


Play, in the Java version, does not have an elegant way to switch the 
language. But that does not hinder us from going a little further to the 
low level. Notice that we set the cookie that defines the language 
directly in response. The 1angCookieName method returns the 
name used by Play to write the cookie. 


Finally, lets add this action in routes. 


1 GET /lang 
controllers.CookieLang.changeLang () 


An important reminder is that once the language cookie has been 
set, Play will always give preference to it in relation to the language 
sent by the browser. To return to the original operation, the user will 
have to clear the browser cookies, or the application will have to 
remove that input from the cookies. If you choose the second option, 
you can use the code below. 


1 public static Result clearChooseLang() { 

2 

response ().discardCookie(Play.langCookieName () ) ; 
3 return 

redirect (routes.ConferencesController.list()); 


5 } 


15.3 Beware the Cache 


In the chapter "Serving different formats", we had a problem with the 
cache because the header Accept was not being respected. The 
solution found was to control the cache manually. Now the situation 
is back again. With our listing being cached, if the user changes the 
language, it will not be reflected on the page. 


A more complete solution would be to have a way to configure the 
headers that should be taken into consideration when making the 
cache. But as the implementation of Play does not accept this, we 
choose a simpler alternative, at least for the moment. Parts of the 
system in which the information present in the headers influences 
the response will not be cached. Therefore, go to the conferences 
controller and remove the implemented cache. Another alternative 
would be to write a Cache plugin that takes into account this type of 
situation. 


15.4 Conclusion 


This chapter has covered the part of internationalization of Play, 
something that is simple, but very common among all applications. 
Once again, everything was integrated into the framework, allowing 
the entire setup to be very easy. Always remember to be careful with 
the messages that depend on parameters; the absence of them will 
make the message appear strange on the page. 


Take extra care with the actions that have been cached if you are 
changing the language and the change is not being reflected in the 
application. Pay attention to this aspect! 


CAPÍTULO 16: 
Deploying the application 


Our application has its core functionality almost implemented. Events are registered, 
moderated, and listed on the homepage. With the authentication part already done, it is 
time to install the project on a server, a process also known as deploy. 


16.1 Running in production mode 


For now we have used to run the ‘play ~run’ command to execute the application. As you 
may have noticed, every change made in the code, both in classes and in settings files, 
was automatically reflected in the system, which is great when running in development 
mode. The problem with this for production is that, to each request, Play performs a 
complete check to verify that there is nothing new in the application, and its response 
becomes slower than it should be. Not to mention, the time to deploy is very important in 
the development life cycle; you do not want your application to update without your 
permission. 


Thinking about this, the framework already provides a specific task for those who need to 
run it in production mode. Just change the run by start. When the ‘play start command is 
executed, it automatically cuts all the checks commented before, and your application 
actually runs in production mode. An important detail in this approach is that you must 
have all the Play infrastructure in your production server. You will need to have Play’s 
SDK installed in addition to your application code. The most common way to do this is by 
installing your code versioning system on the server. For example, if your company uses 
the git, after downloading the SDK, your workflow for performing a deploy would be 
basically the following: 


e git pull origin master(download the latest version of the code) 
e cd folder_of_your_project 
e play start 


Just include it in a script, and you can deploy your project in production mode. Note that it 
is not necessary to install a separate server or copy your project to a specific folder. Quick 
and painless. 


If you do not have permission to install the git and the SDK of Play on your server, which 
is actually quite common, the framework already provides an alternate path. It is possible 
to generate a zip with everything needed to run your application in standalone mode: you 
just have to run the command ‘play dist’. This task will generate a zip in the folder 
target/universal with the name based on this template: project_name- 
version_in_build_sbt. In the case of our project, the generated name is agendatech-1.0- 
SNAPSHO T.zip. 


This zip has all the necessary dependencies to run your project, plus a script ready to 
start the application in production mode. Once extracted, just run the script as follows: 
“agendatech-1.0-SNAPSHOT/bin/agendatech’. Note that the script name is the same as 


in your application. This way is even easier than the first one, since you only need to have 
Java installed on your server! 


16.2 Setting up the production server 


Right now, it would not be unusual if you had some questions in your head. Let’s try to list 
some here. 


e But I do not want to run on port 9000, what do | do? 

e You mean | am going to use the same database development in production? 

e Regarding the settings, | want to use a real email and not the fake one configured. 
e If | change database, will the first user have to run the evolutions for me? 

e Can I run my server with a different memory configuration? 


These are more than fair concerns. As usual, you do not need to think hard to implement 
them. All these settings can be passed as argument to your startup script. For example, if 
you want to change the port, the parameter that should be used is -Dhttp.port=1234. 


| agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=80 


A point that’s a little more interesting is the database change. You already have a base file 
with several configurations; now you just need to change some of these. The first step is 
to create another file. Let’s call it production.conf. The main alteration we will make is for 
using another database for the production system. 


| db.default.url= 
2 "Jdbc:mysql://localhost/agendatech play production" 
3 logger.application=INFO 





Moreover, in a production environment, it is interesting to reduce the level of logging in 
order not to create very large files. It does not make much difference in small systems, but 
if the application that is on your mind is bigger, large logging files usually create many 
problems. 


One situation we have here is that we still need the remaining settings left in 
application.conf. In order not to have to copy everything again and duplicate the code, 
Play offers a way for you to include the settings from one file into another. 


v 





include "application.conf 


3 db.default.url= 
"jJdbc:mysql://localhost/agendatech play production" 
5 logger.application=INFO 





This way you can even modularize your settings: file for setting up authentication, 
database, email, etc. Just remember that if you set a key that already exists in the file 
included, it will be overwritten by the new definition. Now you can even use your real 


email settings! With the production file created, it is necessary to tell Play that we want to 
use it instead of the application. Just pass one more parameter to the startup. 


1 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=80 
2 -Dconfig.resource=production.conf 











It is also possible to pass a path that is out of your project. This is useful for situations 
where the company has a particular branch for these configuration questions. The 
parameter is -Dconfig.file=filepath. 


Now that the database has been altered, the first time the application runs, Play will try to 
apply the evolutions to create the tables. The problem is that it would be very strange if a 
user of your application received that page in which Play presents all the evolutions that 
should be applied! He would know all the system tables—quite a security breach. For 
prevention, let's instruct the framework to apply all the evolutions when starting the 
application. 


1 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=80 
2 -Dconfig.resource=production.conf 
-DapplyEvolutions.default=true 

















You can also alter any key that is present in the configuration file. For example, to pass 
the database password through the command line instead of leaving it written in the file, 
we can do the following: 


1 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=80 
2 -Dconfig.resource=production.conf 
-DapplyEvolutions.default=true 

-Ddb.default.password=yourpassword 




















One last point that you may need is to pass specific arguments from JVM to your 
application. For doing so, Play defines a convention that indicates that this argument is for 
the JVM. 


1 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=80 
2 -Dconfig.resource=production.conf 
-DapplyEvolutions.default=true 
-Ddb.default.password=yourpassword 
-J-Xms512M -J-Xmx512m 




















Any other configuration needed can be passed at the initialization time. Another very 
common one is to indicate a log file other than the default. 


16.3 Scaling out 


Play alone scales more than the vast majority of the frameworks we have in the market. 
According to a study made by ZeroTurnaround company, creator of JRebel, Play is the 


framework that has better performance and scalability than we have in the Java world 
today (http://zeroturnaround.com/rebellabs/the-2014-decision-makers-guide-to-java-web- 
frameworks’). 


Even with all this power because of its fully asynchronous architecture, there is a chance 
that your application, due to a very large increase in the number of requests, may need 
more processing power. Common cases are the deals offered by airlines, e-commerce, 
etc. In these situations, the most common and inexpensive solution is to add new servers 
to meet the demand. Because of virtualization, creating new machines has become a 
simple job. Companies like Amazon or DigitalOcean offer online control panels for these 
machines. This strategy is known as scaling out. Another one also used is to buy a 
machine with a setting far above the average that supports the increasing number of 
requests, also known as scaling up. 


Setting up several servers 


Considering that the chosen technique is scaling out, the first task to be done is to 
configure a few instances of your application. To perform the test at home, simply open 
two tabs of your terminal. 


| bash bash 
bertoluizsouza@Alberto-Luiz-Souzas-MacBook-Pro-3 agendatech (masters) $ 














Fig. 16.1 


Now it is necessary for your application to be started on both. Remember to change the 
server port. 


1 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=8081 
2 -Dconfig.resource=production.conf 
3 -DapplyEvolutions.default=true 














6 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=8082 
7 -Dconfig.resource=production.conf 
8 -DapplyEvolutions.default=true 














So very simple! However, when analyzing this configuration a little further, we fall into a 
problem. How will the user know which server to access? If he needs to specify the port in 


the address to be typed, it will be worthless to create two instances, as the same user will 
always be using the same server. 


Load Balancer 


Therefore, it is necessary to use a third party server that knows the addresses of all 
instances of your application. This server is usually called Load Balancer. There are 
some implementations of it, and the best known are: 


e Apache httpd with the mod_proxy plugin 
e Nginx 
e HAProxy 


HAProxy will be used in this book since it is the only one really focused on performing the 
load balancing. Whatever the choice, you will always have to indicate the addresses of 
the servers in charge of attending the requests. For example, in HAProxy, we will have to 
create a file with the extension .conf. 


1 global 

2 daemon 

3 maxconn 256 
defaults 





mode http 

timeout connect 5000ms 
timeout client 50000ms 
timeout server 50000ms 











Pl option forwardfor 


13 option http-server-close 





frontend http-in 
bind *:8080 
default backend servers 








19 backend servers 
20 balance roundrobin 





option httpclose 
option redispatch 


server playl 127.0.0.1:8081 maxconn 32 
26 server play2 127.0.0.1:8082 maxconn 32 
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The content of the configuration is not the most important. Let's look at just a few points. 


e timeout: waiting times for the steps that HAProxy must follow. For example, being 
able to connect to one of the configured servers. 


e forwardfor option: causes HAProxy to pass the original IP of the request by the 
header "X-Forwarded-For". 

e bind: indicates that HAProxy will listen to requests on the specified port. Generally the 
port is 80. 

e server: server address that will be used by HAProxy to pass the requests. 


Now that the two servers with Agendatech are already running and we have the 
configuration for Load Balancer, just initialize HAProxy. Its startup script only works for 
Linux and Mac, so if you are on Windows you will have to download Cygwin and perform 
the installation. For the other users, just use apt-get for Linux or brew for Mac. With 
HAProxy installed, we can run the initialization command. 








| haproxy -f haproxy.conf 


If you run the haproxy command from another folder, just include the path of the setup 
file. Okay, you can now browse at will through Agendatech without knowing which 
instance is serving your application. If the application needs more instances, just create 
another server and add the entry to the setup file. Another interesting point is that if any 
server has a problem, the application will continue running. This is what we call 
availability. 


16.4 Stateless helping on scalability 


An interesting detail is that our application saves the data of the user logged in to the 
session. Using the traditional framework of the Java world, theses data will be in an 
HttpSession that is linked to the server that attended the login request. The problem with 
this approach is that, once the user has logged in, it can only be directed to the same 
server because its data is there! To resolve this, the Load Balancers accept a 
configuration where a link can be made between the session id of the user and the server. 
Thus, every time the user tries to access the application, he will be directed to the same 
server. This concept is called Sticky Session. 


This problem does not exist in Play. As there is no concept of session, since all the data 
stored there are placed in the client cookie, you do not need to worry about which server 
will attend the request. The data needed to answer the request will always be coming 
from the client! Being stateless makes your application really able to take full advantage 
of all the servers that have been added to attend the clients. 


16.5 Https 


HTTPS is the standard way to encrypt requests between the client and an application that 
uses HTTP as the transport protocol. The point here is not getting into details about 
specification, but rather, it is how to make your application take advantage of it. 


For your application to really have a secure connection, your company must get a 
certificate from a company that is widely accepted by the most used browsers in the 
world. Browsers are the key because they are the largest part of the client applications of 
web systems. A very interesting presentation about HTTPS and certificates can be found 
at this link (http://www.youtube.com/watch?v=Z7WIZ2FW2TcA). 





If your company has done all of the necessary process, you will need to inform Play 
where the generated file is that contains the certificate and signature, plus the password 
used to generate it. 


1 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=8080 
2 -Dconfig.resource=production.conf 
-DapplyEvolutions.default=true 
**—-Dhttps.port=9001** 
**—-Dhttps.keyStore=mykeystore.jks** 
*x—-Dhttp.keyStorePassword=mypassword** 

















Note that you need to specify in which port your application will attend the requests using 
HTTPS. An interesting detail is that often you want to add the HTTPS even without a 
recognized certificate, a common case for intranets, for example. Play also helps you in 
this scenario. Instead of having to use the JDK utility called keytool, you simply pass the 
HTTPS port and not any other configuration. 


1 agendatech-1.0-SNAPSHOT/bin/agendatech -Dhttp.port=8080 
2 -Dconfig.resource=production.conf 
3 -DapplyEvolutions.default=true 
*x—-Dhttps.port=9001** 














Play automatically generates a signed certificate and uses it to handle the request 
encryption. The file will be generated in the conf folder with the name 
generated.keystore. 


16.6 Deploy in cloud 


Nowadays, in addition to clouds that provide infrastructure such as Amazon and 
DigitalOcean, also known as IAAS (Infrastructure As A Service), there are the clouds that 
already offer a platform ready, like Heroku, CloudBees, OpenShift, etc., known as PAAS 
(Plaftorm As A Service). The main difference is that the second group already has 
everything ready for you to deploy your application: installed server, runtime on the 
installed language, database, and so on. 


As the Play framework is already well known in the market, many of these PAAS now offer 
ready integration. Let's look at an example using Heroku. 


Deploy in Heroku 


Initially, you need to install the program from Heroku’s command line. A tutorial can be 
found at this address: https://toolbelt.heroku.com/ . After this part, the process is very 
simple. The first step is to create a new application that runs on Java on Heroku. For that, 
we should run the following command inside the folder of our project: 





| heroku create agendatech-play-book 


Heroku already has a fine integration with the Git file versioning system, which this author 
recommends to be used by the reader. To install Git, follow this tutorial provided by Github 
(https://help.github.com/articles/set-up-git). With Git installed, just add the versioning 
control to your project. Perform the following steps inside the project folder: 


e git init 
e git add -A 
e git commit -m "first commit" 


Now just send the code of your application to Heroku! 
1 git push heroku master 


Once your application has been deployed, just access it through the creation name of the 
same (agendatech-play-book.herokuapp.com). An important detail is to check the 
database configuration required. See the Heroku documentation. 


This is a point in favor of the clouds. The facility became so large that it is difficult to 
decide whether to create a proper infrastructure or take advantage of these features. 


16.7 Conclusion 


This entire chapter was devoted to the time of deploying your application. Generally, this 
should be a time of happiness for programmers. After all the work is finally published, 
however, it becomes a moment of tension because of the steps required to install the 
application. 


Play tried to minimize this very work, at least regarding the application itself. Everything 
needed for production can be passed via argument, which makes it much easier. Once 
the command line is placed in an execution file, you no longer need to change it. Other 
interesting points related to the deploy automation are: 


e Database backup in regular intervals. 


e Backup of the application that is in production at the time. 
e Configuration of the hardware running the application, for easy replication. 


16.8 See you 


With what you already have, you are now able to develop any application! Do not wait too 
much. Try using the framework in your next project; after all, practice makes perfect. 


Thank you for taking your time to read this book. | hope that reading it has been as useful 
for you as it was for me writing it. Any questions you have, feel free to send me an email 
(playnapratica@gmail.com). | will be continuously attentive. You can also find me on 
twitter by user @alberto_souza. l'm always posting interesting links about Play. 


The next chapters will discuss more specific parts of the framework, such as plugins and 
evolutions. 


CAPITULO 17: 
Reusing functionalities by means of plugins 


One of the functionalities implemented in Agendatech is the one that 
sends an email for each new conference that is registered in the 
system. Since sending emails is a very common task, rather than 
implementing this code by hand, a specific plugin was made for 
sending emails. Using plugins is a very important part of your projects 
because many times the functionality you are going to implement is 
already there! 


For example, the upload code we wrote for registering a photo 
associated with the event was quite hardworking. Let's take a look 
just to refresh the memory. 


1 private static File saveFeatureImage() throws 
IOException { 

2 RequestBody requestBody = 
request () .body(); 

3 MultipartFormData body = requestBody 

4 .asMultipartFormData(); 

5 FilePart filePart = 
body.getFile("featureImage"); 

6 if (filePart == null) { 

7 return null; 

8 } 

9 File featureImageUploaded = 
filePart.getFile(); 

10 File newImage = new 
File ("public/images/feature images", 

J System.currentTimeMillis() + ™ 
12 + filePart.getFilename()); 
13 FileUtils.moveFile (featureImageUploaded, 
newlmage) ; 

14 return newlmage; 

15 } 





We had to handle saving the file and the definition of its name. 
Moreover, a detail that we did not care about was the fact that we will 
probably want to treat this image that was posted by the user. For 
example, we may want to adequately resize it to the layout of our 
application. So as not to have to do that every time, let's create a 
plugin that isolate this code and allow us to reuse it in other projects. 


17.1 Using and implementing the plugin 


Before we get into the implementation, let's look at the example for 
our plugin. It is always important to remember that, when building an 
API that will be used by many users, the methods that are presented 
to be used are the most important part. How they are to be 
implemented is not so important to us. Let's start focusing on this! 


The first point that the user of our plugin will need to access is the 
class that presents him the functionalities of our extension. 


import play.Play; 
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PaperClipPlugin plugin = Play 
.application().plugin(PaperClipPlugin.class); 
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The method plugin acts as a Factory Method. Notice that a 
parameter is passed to the class that represents its component, and 
the method returns an object ready for use. Not much work, as usual. 
The PaperClipPlugin class needs only to implement the interface 
play.api.Plugin. 


1 public class PaperClipPlugin implements Plugin{ 


private Application application; 
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5 public PaperClipPlugin (Application 
application) { 
6 this.application = application; 


~~ 


} 
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@Override 





10 public boolean enabled() { 
Ll return true; 
12 } 
13 
14 @Override 
15 public void onStart() { 
16 Logger.info ("Starting PaperClip plugin"); 
17 } 
8 
19 @Override 
20 public void onStop() { 
21 Logger.info("Stoping PaperClip plugin"); 
22 } 
23 } 


We are required to receive the parameter of the type Application in 
the constructor. Through this parameter you can know, for example, if 
you are in a development or production environment. 


One of the functionalities of our plugin is to allow a photo to be cut in 
the center. Here's an example: 
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UploadedImage image = 
UploadedImageFormatter 
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.toUploadedImage (request (),"featureImage"); 

UploadedImage croppedImage = plugin 
.centeredCrop (image, 200,200); 

croppedimage.save ("feature images"); 
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The component already provides the method that makes the cut. The 
other detail is that we must transform the uploaded file into an object 
of the type Uploadedimage. Here we can even improve and 
transform this Formatter into a standard converter of Play. That way 
we could have such an attribute in our model. Note that all that messy 


upload code is gone. We have a much simpler implementation, and it 
is one that can be reused in other projects. 


We will talk about it in the next section, but it is better that the plugin 
source is in another project, precisely for the same to be reused 
across multiple applications. Given this context, we need to notify 
Play that the plugin should be loaded. The file in charge of this is the 
play.plugins. Such a file has already been used when the email 
plugin was configured. 


1 1500:com.typesafe.plugin.CommonsMailerPlugin 


10500: com.github.asouza.play.paperclip.PaperClipPlu 
gin 


Just as a reminder, the number that comes forward has to do with the 
loading order of the plugins. Above 10000 means that we want it to 
be loaded after executing the Global class, which is at the root of the 
project. If you are curious, access this link (http://bit.ly/1gVbHI7) and 
see some of the plugins that are loaded when the application starts. 


Okay, now we can easily use the upload plugin in our projects. The 
full code is on github. To verify, access this address 


17.2 Details on implementing a plugin 


To create a plugin, some precautions should be taken. As mentioned, 
it is better that the code is in another project so it can be reused. The 
problem here is that you will need the Play dependencies. The 
easiest way to fix this situation is to create a new project using Play! 
This way everything will already be configured, and you will only need 
to worry about its implementation. 


Another detail that should be taken care of is the files in the 
configuration folder. Whatever is inside there is available in the 
classpath of the application, and if you leave, for example, the file 
routes in there, there is a chance it may be used instead of the 
routes of the application that is using the plugin. Usually you should 
find, in the conf folder of your plugin, files of specific settings, such as 
the ones for internationalization of the keys used by it. 


17.3 Publishing 


Once the plugin is written, it is important that you can test it in your 
application locally and then release it for use by other projects around 
the world. 


Following the common way, let's add the dependency on the file 
build.sbt. 


libraryDependencies ++= Seq ( 
#outras libs, 
"com.github.asouza.play" %% "play-paperclip" % 
"1.0-SNAPSHOT" 
4 ) 


With a further analysis, how is the sbt going to resolve this 
dependency if we have not yet published anywhere? To solve the first 
part of the problem, we will publish it only locally. In the application 
console of your plugin, just type publishLocal. This will now 
register the plugin in the local repository of the Play installation. 
Another detail is that you need to add the name of the organization to 
your build file. For example, the upload and any other that this author 
will write will be under the organization com.github.asouza.play. 


1 #rest of the file 


3 organization := "com.github.asouza.play" 


After testing it locally, you will probably want to release your plugin to 
the world. To do this you just have to make some other settings in the 
build file. 


1 #rest of the file 


3 publishTo := Some("Sonatype repo" at 
4 "https://oss.sonatype.org/releases"), 


The Sonatype is famous for hosting several libs widely used in our 
projects. Besides indicating the address of the publication, we need 
to have the necessary credentials to publish the library. For the 
publication to be successful, you need to make the necessary 
settings in Sonatype. The complete guide can be found at 
http://bit.ly/1kxnTYx. 


With everything set up, just access the plugin console and type 
publish. 


17.4 Conclusion 


The plugin is a powerful way to create reusable components. Much of 
Play itself is implemented as a plugin. For example: 


e Association of routes with the actions. 
e Loading the Global class. 
e Running the evolutions. 


Take advantage of this functionality, try to leave as much reusable 
infra code in plugins as you can. This way your project will always be 
much more focused on business rules. 


CAPITULO 18: 
Taking care of the database evolution 


In a few moments during the development of our application, we had 
to create tables and new columns in the database. To address this 
important part of the development process, Play provides us the 
mechanism of evolutions. By the way, we have already written 
some! 


The reader who knows a little of Hibernate may be wondering what 
advantage the evolutions provide for the table update mechanism 
that is already embedded in Hibernate. For the reader who is not 
familiar with Hibernate, it provides a setting that makes you go on 
creating tables and new columns in the database as you change our 
models annotated with ‘@Entity’. 


1 <property name="hibernate.hbm2ddl.auto" 
value="update"/> 


This is a good question and deserves some items for reflection. Let’s 
imagine some situations. 


In the definition of the class Conference, we took care of adding an 
annotation on the attribute description to advise that it should 
represent a column of the type text in the database. 


1 @Entity 

2 public class Conference { 

@Column (columnDefinition = "text") 
private String description; 
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Had we not done so, now would be the time. The problem is that this 
alteration would not reflect in the database, since it does not change 
what has already been created. You would probably have to make 


an SQL script to make this change. And when the other developer of 
the team updates the project, how would he know that he would also 
have to change his development database? 


Another situation is the need to delete an attribute in its class. As 
your application no longer needs to maintain that state, why keep the 
same status in the database? Once again, you fall into the problem 
of having to write an SQL script to implement such change in the 
database. And once again, another developer will have to find out 
that an alteration should be applied in the local version of his 
database. 


And even if your team can solve all these situations, how will these 
changes go into production? Usually the production database is in a 
controlled environment where changes must be manually applied 
and not directly through the application. 


For these reasons, if you let the persistence framework keep 
changing the database according to the model, it will work 
reasonably well for the development of small systems, but soon it will 
get very confusing for larger systems. And the loss of visibility of 
changes is one of the biggest reasons. 


There are already some tools on the market that precisely resolve 


this problem. And Play, as a full stack framework, already has this 
built in. 


18.1 Evolutions in Play 


Our application is already evolving the database through the creation 
of SQL files. 


1 # --- !Ups 


3 alter table conference add start date date; 
4 alter table conference add end date date; 


# --- !Downs 


11 alter table conference drop column start date; 
12 alter table conference drop column end date; 


Notice that the file is split into two parts: the !Ups comment defines 
the snippet that should evolve the database, while the ! Downs 
defines the snippet that unmakes the evolution. Just like everything 
related to the configuration, these files are inside the folder conf of 
the project. Still inside the conf folder, the evolutions/default folder 
was created, which really contains the SQL scripts. The name 
default comes from the fact that we configured the Ebean server 
with this same name. 


ebean.default="models.*" 


If the application worked with two different databases, you could 
have other folders inside evolutions. 


To guarantee the execution order of the evolutions in a way that is 
easy to understand by the developer, a number is used at the 
beginning of each file. For example, for the evolution that adds dates 
to the event, the chosen name was °2.sqI’. 


Which evolution needs to be executed? 


When another developer downloads the latest updates of the code 
and runs the application, the framework must decide which 
evolutions are still to be applied. There is a table created exclusively 
to perform such control. 


2 | Field | Type | Null | Key | 


Default 
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4| id | int(11) | NO | PRI | 
NULL 

5 | hash | varchar(255) | NO | | 
NULL 

6 | applied at | timestamp | NO | | 
TIMESTAMP 

7 | apply script | text | YES | | 
NULL 

8 | revert script | text | YES | | 
NULL 

9 | state | varchar (255) | YES | | 
NULL 
10 | last _ problem | text | YES | | 
NULL 
11 +--------------- +-------------- +------ +----- +-- 


As it is for internal use, Play itself carries out the creation of the table 
automatically. For each evolution applied, it creates a record in this 
table with the data in it. In this way, the framework can know which 
evolutions have been implemented and which are still missing. 


18.2 Common problems 


The standard nomenclature of evolutions has worked very well so 
far. Including a number at the beginning of the file clearly indicates 
the order that the evolutions must be performed. One possible 
problem may appear if you are working in a team with more 
developers. Consider the following situation: The system must now 
have two new functionalities. They are association of an conference 
to a group in charge of its organization and registration of banners 
that can be displayed in Agendatech. 


You are responsible for implementing the first functionality, and 
another Developer—let's call him Wolverine—is responsible for 
making the part of the banners. Wolverine, in his machine, creates a 
new evolution to be applied to the database, for example 6.sq/. 





1 + s=- [Ups 

2 

3 create table banner ( 

4 id integer auto increment not null, 
5 name varchar (255), 

6 constraint pk banner primary key (id)) 
8 

9 
10 
11 
12 # --- !Downs 
13 
14 SET FOREIGN KEY CHECKS=0; 
15 
16 drop table banner; 
e ih 
18 SET FOREIGN KEY CHECKS=1; 


As usual in systems with many developers, the team uses some 
version control, for example GIT. After making his implementation, 
Wolverine sends his changes to the server. On your side, you also 
begin to implement your functionality and also create a new 
evolution called 6.sql_. Before sending your changes to the server, 
you must download the latest updates, and there lies the problem. 
The GIT will accuse a conflict issue, which the developer is obliged 
to resolve. Probably, after resolving the conflict, your evolution 
turned out this way. 


1 # === !Ups 
2 
3 create table banner ( 





4 id integer auto increment not null, 
5 name varchar (255), 

6 constraint pk banner primary key (id)) 
l; 

8 

9 create table conference group ( 
10 id integer auto increment not null, 
11 name varchar (255), 
12 constraint pk conference group primary key 
(1d) ) 

Loy 

14 

15 

16 

17 

18 # --- [Downs 

19 
20 SET FOREIGN KEY CHECKS=0; 
21 


22 drop table conference group; 
23 drop table banner; 

24 

25 SET FOREIGN KEY CHECKS=1; 


When you try to access the application again, Play will realize that 
this evolution has already been applied, but it had been changed. 
Based on this, it will show the error page suggesting that you apply it 
again. 


Database 'default' needs evolution! 





An SQL script will be run on your database - EM a 


This SQL script must be run: 


1 # !!! WARNING! This script contains DOWNS evolutions that are likely destructives 
2 

3 # --- Rev:6,Downs - 17d9267 

4 SET FOREIGN_KEY_CHECKS=0; 

5 

6 drop table banner; 

7 

B SET FOREIGN_KEY_CHECKS=1; 

9 

10 # --- Rev:6,Ups - 9c9ald2 

11 create table conference_group Ç 

12 id integer auto_increment not null, 
13 name varchar(255), 

14 constraint pk_conference_group primary key Cid)) 

aon; 

16 

17 create table banner ( 





18 id integer auto_increment not null, 
19 name varchar(255), 
29 nstrai ni 
. 
Fig. 18.1 


Just click on the application button of the evolution, and your 
problem will be solved. 


Another very common situation is when the evolution contains an 
invalid SQL. For example: 


# --- !Ups 


create table participation ( 
id integer auto increment not null, 
conference id integerrr not null, 
user::id:: integerrr not null, 
constraint pk participation primary key (id)) 


OrnrAA OF WN FE 


Ne 


In this case, the type integerrr is written wrongly. As it is the default 
when the application is accessed, Play will try to apply the evolution. 


Database ‘default" is in an inconsistent state! 





An evolution has not been applied properly. Please check the problem and resolve it manually before marking it as resolved - 


We got the following error: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right 


syntax to use near ‘integerrr not null, user_id_ integer not null, constraint pk_pa' at line 3 [ERROR:1064, SQLSTATE:42000], while trying to run 
this SQL script: 





# --- Rev:7,Ups - 2358e8e 


create table participation ( 

id integer auto_increment not null, 
conference_id integerrr not null, 

user_id_ integer not null, 


constraint pk_participation primary key Cid)) 


Fig. 18.2 


And as expected, as the script is with an SQL error, the evolution is 
not completed successfully. As the message itself suggests, the 
evolution should be corrected manually. After that, just try to access 
the application, and the application of evolutions standard page will 
be displayed. 


18.3 Other tools 


Play’s default implementation of evolutions helps a lot during the 
development. Just as a Curiosity, it is interesting to Know that there 
are other tools with the same goal. For example, some users 
complain that in Play there is no way to apply these evolutions by 
command lines, or even programmatically. Another point not 
implemented is the lack of possibility to rollback any evolution 
applied. If your application needs any of these functionalities, you 
can try some of the tools listed below. 


e Mybatis migrations (http://mybatis.github.io/migrations/) 
e Liquibase (http:/Awww.liquibase.org/) 





Flyway already has a plugin for integration with SBT, and as SBT is 
the building tool of Play, you can use it inside your project. The same 


18.4 Conclusion 


The aim of this chapter is to provide more details about the 
evolutions of Play. The point that deserves more attention is the 
nomenclature that will be used in the files. Recall that in an 
environment with more than one developer, which is common, you 
need to have a strategy of names good enough to minimize the 
number of conflicts. Using the timestamp is likely to be a good 
solution. 


CAPITULO 19: 
Time to practice 


Thank you so much for being with me along the journey of this book! 
It is very important that you try to practice everything that has been 
studied in the book. Is there a chance to choose the technology of 
the new project? Don’t be shy; use Play and focus on your business 
rules, providing much more value to your client, not to mention that, 
even with this old saying, “practice makes perfect’, in every new 
project, you will find new challenges that will make you understand 
more and more about the framework. 


19.1 Keep in touch 


| am absolutely available to assist you whenever possible. You can 
find me in the following ways: 


e By email, just send a message to playnapratica@gmail.com. 

e If you use twitter, just access https://twitter.com/alberto_souza. 

You can also follow my projects at github. Simply access 

https://github.com/asouza. 

e Also, visit my blog where you will find several posts about Play. 
The link is http://alots.wordpress.com/. 


Finally, any feedback about the book is welcome. If you want to send 
it directly to my email, feel free to do so. Writing the book 
independently was a great challenge, | hope it has been worth it to 
you! 


19.2 Consultancy and events 


Do you need to start with Play in your company? Get in touch! | will 
be happy to assist you. 


